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5.1 INTRODUCTION 

File management on a VMS system involves moving files between devices, directories, 
and/or systems; protecting files from undesired manipulation; and maintaining and 
organizing collections of files in a directory. 

The VMS system provides the following means to help manage files: 

Devices that store files. 

A file system that organizes, protects, and retrieves files stored on the system. 

Commands and utility programs that allow you to communicate with the devices 
and the system. 

This module shows you how to organize and maintain a collection of files. 

5.2 OBJECTIVES 

To store and retrieve the many files used during daily operations, and to protect these 
files from unauthorized use, a user should be able to: 

Locate files in directories 

Locate directories in directory trees 

Locate directory trees on volumes 

Locate volumes on devices 

Display contents of files 

Add and remove files from a directory 

Locate files on tape volumes 

Specify devices that do not support files 

Protect files from access by unauthorized users 



5.3 RESOURCES 

Guide to VMS Files and Devices 
VMS DCL Dictionary 
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5.4 NAMING A FILE 

This section describes the necessary terminology for a user to effectively perform daily 
tasks on a system. The following sections give a more detailed explanation of devices, 
directories, file names, file types, and version numbers. 

5.4.1 File Specifications 

A file is a logically related collection of records. You name a file on a VMS system 
by giving it a file specification. The file specification is broken into five parts. Each 
part gives the system a different piece of information it needs to locate the file. The 
system distinguishes one part from another by the location of special characters called 
delimiters that you place within the file specification. 

5.4.1.1 Use of Delimiters in a Local Disk File Specification 

DEVICE: [DIRECTORY] FILENAME. TYPE; VERSION-NDMBER 
12 3 4 

1 : specifies the end of a device name 

2 [ and ] specifies the beginning and end of a directory name 

3 . specifies the beginning of a file type and end of a file name 

4 ; specifies the beginning of a version number 
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Table 5-1 shows the parts of a file specification and their syntax. 
Table 5-1 Syntax of a Local Disk File Specification 

DBAO: [SMITH] MYFILE.DAT; 7 



Part 


Reference 


Rules of Naming 


Example 


Device 


Storage device name 


1 to 255 characters 


DBAO: 


Directory 


Catalog of files 


1 to 39 characters 


[SMITH] 


Name 


Name of file 


to 39 characters 


MYFILE 


Type 


Kind of file 


to 39 characters 


DAT 


Version 


Unique number used to 
differentiate files with the 
same name and type 


1 to 32767 (integer) 


7 



The following characters are allowed in directory names, file names, and file types: 

A through Z 
through 9 
Underscore (_) 
Dollar sign ($) 
Hyphen (-) 



The system interprets all alphabetic characters in file names and types as uppercase 
letters. 



NOTE 

DIGITAL systems use the dollar sign ($) in a number of system-wide 
variables. Therefore, to minimize confusion, it is recommended not to use 
the dollar sign in user-defined file specifications. 
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5.5 DEVICE SPECIFICATIONS 

A device specification can consist of one of the following: a logical device name, a 
physical device name, or a generic device name. A logical device name is a synonym 
for a physical device name, usually established by the system manager. A physical 
device name refers to a specific physical device on the system. It has the following 
components: 

A device code indicating the type of device you want to use. 

(For reasons internal to VMS, the device code is not always the same as the first 
two characters of a device type. See the list of device types in Table 5-17 of 
Appendix A of this module.) 

A controller character indicating the controller to which the desired device is 
attached. 

A unit number indicating the relative location of the desired device among the 
devices on the particular controller. 

Table 5-2 illustrates the components of a physical device name. Table 5-17 of Appendix 
A lists the device type and device code for the most commonly used physical devices. 



Table 5-2 Naming 


a Device 






Device 
Specification 


Function 


Value 


Default 
Value 


Device type code 


Identifies device type 


2-13 characters 


None 


Controller character 


Names controller to which 
device is attached 


One or more of the 
characters A-Z 


A 


Unit number 


Names relative position 
on controller of desired 
unit 


Decimal numbers 
from 0-65535 





Device 

specification 
delimiter 


Marks the end of the 
device specification 


: (colon) 


None 



NOTE 



Refer to Appendix A of this module for further information regarding devices. 
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5.5.1 Peripheral Devices 

A typical VMS system may have a large number of peripheral devices. These devices 
are classified as either mass storage devices or record- oriented devices. Disk and tape 
drives are examples of mass storage devices, while terminals, printers, and card readers 
are examples of record-oriented devices. To use a peripheral device, you must describe 
its location to the operating system by giving a device specification. For example, 
LPAO: represents a particular line printer on the system. 

5.5.2 Logical Names Used to Represent Device and File Specifications 

The VMS system allows you and the system manager to define logical names to be 
used in place of part or all of a file specification. For example, in the file specification: 

DBAO: [SMITH] MYFILE.DAT; 7 

you can equate the device name DBAO: to the logical device name DISKJUSER, and 
then write the file specification as: 

DISK_USER: [SMITH] MYFILE.DAT; 7 

By using the logical device name DISK_USER, the system manager achieves device 
independence. When desired, the system manager can move the file structure from the 
device named DBAO: to a free device, device DBA1: for example, and equate the 
logical device name DISKJJSER to the device named DBA1:. Users can continue 
to specify files with the logical device name DISKJJSER even after the device has 
changed. 

This module uses logical names defined by the system manager only. User-defined 
logical names are discussed in the Customizing the User Environment module. 
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5.6 DIRECTORY STRUCTURE 

All files stored on a disk are listed in a directory of some type. Each disk has one 
master file directory (MFD) that catalogs all user file directories (UFDs). Your default 
directory is one of many UFDs. Each directory has a specific name that can be used 
in file specifications. The conventions for naming the MFD and UFDs are shown in 
Table 5-3. 



5.6.1 The User File Directory (UFD) 

Each UFD contains an alphabetical list of file names and pointers to files. It has a 
protection code that prevents other users from viewing or accessing its contents. A UFD 
is implemented by a disk file and has a file type of DIR. 

Files are placed in your UFD in one of the following ways: 

You can create files in your UFD by using an editor such as EDT or EVE. 

Another user can place files in your directory. 

Files can be copied from another source. 

Some programs, when executed, can produce files as output 
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5.6.2 Directory Names in the Hierarchy 



Table 5-3 Directory Names 



Directory Type 



Example 



Naming Convention 



Master File 
Directory (MFD) 

User File 
Directory (UFD) 



[000000] 



[SMITH] 



Each disk contains one MFD, named 
[000000]. Given by the system. 

The owner's user name is the Level 1 
directory name in most instances. 



Subdirectory (SFD) [SMITH.PAYROLL] You choose the names for the 

subdirectories you create. 



Figure 5-1 illustrates Master File Directories and User File Directories in the hierarchy. 
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MFD 
LEVEL 



UFDs 
LEVEL 1 



SFDs 
LEVEL 2 



SFDs 
LEVEL 3 



[000000] 



[USER1] 



[SMITH] 



[SMITH. PAYROLL] 



[SMITH. INVENTORY] 



[SMITH. PAYROLL. MODULES] 



[SMITH. PAYROLL. DOCUMENTS] 



TTB_X0327_88 



The names given in the rectangles are directory names. 
Figure 5-1 Naming Directories 
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5.7 DEFAULTS FOR FILE SPECIFICATIONS 

Each part of a file specification is called a field. The system supplies defaults for each 
field. To use the default value for a field, omit the value for the field. To override the 
default value for a field, supply a value for the field. Table 5—4 shows the parts of the 
file specification and the defaults for each part. 



Table 5-4 File Specification Defaults 



Part of File 
Specification 



Default 



Device 

Directory 

Name 

Type 

Version 



Device established at login by the system manager 

Directory established at login by the system manager 

None 

Depends on the DCL command 

The highest version number 



For example, the following file specification specifies the highest version of the file 
named MYFDLE.DAT, catalogued in the directory named [SMITH] of the volume 
mounted on the disk drive named DBAO:. 



DBAO : [ SMITH] MYF ILE . DAT ; 7 

Note that the node name is not utilized when you access a file on your local node, 
and the version number of 7 signifies that the highest version of MYFTLE.DAT is 
MYFILE.DAT;7. 
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5.7.1 Using Temporary Default Fields Within a Parameter 

DCL establishes temporary file specification default fields within a command parameter 
that has more than one file specification. Each file specification within the parameter 
is used to establish temporary field defaults for subsequent file specifications. By 
taking these temporary defaults, the VMS system minimizes the typing you have to 
do. Temporary defaults are established for the following file specification fields: device 
name, directory name, file name, and file type. (Recall that the node name is not utilized 
when you access a file on your local node and that the version number always defaults 
to the highest version number.) 

Because of the temporary defaults established by DCL, the results of the following two 
commands will be the same: 

$ PRINT DBAO: [SMITH] FILE1 .LIS, DBAO : [SMITH] FILE1 .DAT, DBAO : [SMITH] FILE2 -DAT 
$ PRINT DBAO: [SMITH] FILE1, .DAT, FILE2 

Note that the first PRINT command consists of file specifications that do not utilize 
the temporary defaults established by DCL. The second PRINT command utilizes the 
following DCL temporary defaults: 

1. The file specification DBA0:[SMITH]FILE1 takes advantage of the default file 
type LIS, which is associated with the PRINT command. (Note that you do not 
place the period (.) after the file name FELE1. If you use the period delimiter, the 
system assumes the file has a null file type.) 

2. The file specification .DAT utilizes the following temporary defaults: 

Device name - DBAO: 
Directory name - [SMITH] 
File name - FDLE1 

(Note that the file type DAT is used to establish a temporary default.) 

3. The file specification F1LE2 utilizes the following temporary defaults: 

Device name - DBAO: 
Directory name - [SMITH] 
File type - DAT 

Table 5-5 shows examples of operations you can use to manipulate files in your default 
directory. 
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Table 5-5 Manipulating Files in Your Default Directory 



Operation 



Comments and Examples 



Copying a file 



Changing existing 
file name to new 
file name 



Removing a file 



Removing files on 
an interactive basis 



The COPY command creates a new file from an old file. 

$ COPY DISK: [SMITH] OLD .TXT DISK: [SMITH] NEW. TXT 

(or) 

$ COPY OLD. TXT NEW. TXT 

The RENAME command changes the file name, file type, or 
version number of an existing file. 

$ RENAME DISK: [SMITHJOLD.TXT DISK: [SMITH] NEW. TXT 

(or) 

$ RENAME OLD . TXT NEW . TXT 

The DELETE command removes a file. 

A specific version number must be used to remove a file. 

$ DELETE DISK: [ SMITH] MYFILE . TXT; 2 

(or) 

$ DELETE MYFILE. TXT; 2 

The /CONFIRM qualifier initiates a system prompt to confirm 
whether or not the file should be deleted. 
A "Yes" response deletes the file; a "No" response does not 
delete the file. 



S DELETE /CONFIRM DISK: [SMITHJMYFILE.TXT;* 

(or) 

$ DELETE/CONFIRM MYFILE.TXT;* 

System prompts: 

DISK: [SMITH] MYFILE. TXT; 3 delete? [N] 
DISK: [SMITH] MYFILE. TXT; 2 delete? [N] 
DISK: [SMITHJMYFILE.TXT;! delete? [N] 
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Table 5-5 (Cent.) Manipulating Files in Your Default Directory 



Operation 



Comments and Examples 



Removing all The DCL command PURGE removes all but the highest 

versions of all files numbered version of all files. 

except the latest 

version $ purge 

The PURGE command used with a file specification removes all 
but the highest numbered version of that file. 

$ PURGE MYFILE.TXT 

Appending one or The APPEND command adds the contents of one or more files 
more files to the to the end of the specified output file. In this example, two files 

end of another file are being appended to the output file. 

$ APPEND MYFILE.TXT, OLDFILE.TXT NEKFILE.TXT 

Searching files for The SEARCH command searches one or more files for the 
all occurrences of specified string(s) and lists all lines containing the specified 
the specified search string(s). In this example, the search string "March 13" must 
string(s) be enclosed in quotation marks because it contains a space 

character. 

$ SEARCHMYFILE.TXT "March 13" 



Comparing contents 
of two files 
and displaying 
differences 



The DIFFERENCES command compares the contents of two 
files and creates a listing of the records that do not match. 

$ DIFFERENCES MYFILE.TXT YOURFILE.TXT 



Controlling the 
listing output from 
differences 



The /OUTPUT qualifier tells the system to send the listing of 
differences to a file. The default output is usually the terminal. 

$ DIFFERENCES/OUTPUT=DIFF.TXT MYFILE.TXT YOURFILE.TXT 
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5.8 FINDING FILtS ANu DEmRMiNING TmiiK 
CHARACTERISTICS 

As you create files and add them to your directory hierarchy, your collection grows 
rapidly in size and complexity. You find yourself increasing the use of files listed in 
other directories and stored on other devices. To work in such an environment, you 
should be able to locate particular files among the thousands stored on the disks and 
tapes of your system. 

The operating system includes a powerful utility that helps you locate and display 
the characteristics of files. To invoke this utility, enter the DIRECTORY command, 
followed by one or more command qualifiers and a file specification. You use the 
DIRECTORY command to find files on the peripheral storage devices of your system. 
It can also display the contents of directories or the characteristics of files. 

This section shows how to use the DIRECTORY command to find a file and determine 
its: 

Owner UIC 
Protection code 
Size 
• Date of creation or modification 

Table 5-6 shows the commands used to find and determine the characteristics of files. 
Examples 5-1 and 5-2 demonstrate the use of the commands discussed in Tables 5-5 
and 5-6. 
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Table 5-6 Commands Used to Find and Determine the Characteristics of Files 



Operation 



Comments and Examples 



Listing all files in 
your directory 



Checking for a 
unique file in your 
directory 

Obtaining all 
information about 
a particular file in 
your directory 



Determining the 
size of files in your 
directory 



The DIRECTORY command lists all files and information about 
them in your directory. 

$ DIRECTORY 

The file specification must be included to obtain information 
concerning a particular file in your directory. 

$ DIRECTORY MYFILE.TXT 

The /FULL qualifier overrides the default directory display, 
which is BRIEF. Omit the file specification to obtain full 
information about all files in your directory. 

$ DIRECTORY/FULL MYFILE.TXT 

(or) 

$ DIRECTORY/FULL 

The /SIZE qualifier lists the size of files in 512-byte blocks used. 

The /SIZE=ALL qualifier lists the size of files both in blocks 
used and blocks allocated by the system. 

$ DIRECTORY/SIZE MYFILE.TXT 

(or) 

$ DIRECTORY/SIZE=ALL MYFILE.TXT 
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Table 5-6 (Cont.) Commands Used to Find and Determine the Characteristics of 
Files 



Operation 



Comments and Examples 



Finding files 
created or modified 
before or after a 
specified time 



The /BEFORE= qualifier selects those files that are dated before 
the specified time. 

The /SINCE= qualifier selects those files that are dated after the 
specified time. 

Both the /BEFORE and /SINCE qualifiers can also use the 
keywords YESTERDAY, TODAY, and TOMORROW. 

The /CREATED qualifier is the default. It selects files based on 
their creation date. 

The /MODIFIED qualifier selects files based on the dates they 
were modified. 



Determining 
the owner and 
protection of a file 



$ DIRECTORY/BEFORE=09:00/CREATED MYFILE.TXT 

(or) 

$ DIRECTORY/SINCE=YESTERDAY/MODIFIED OLD.RNO 

The /OWNER qualifier determines if the owner's UIC will be 
displayed. 

The /PROTECTION qualifier determines if the protection of the 
file is displayed. 

$ DIRECTORY/OWNER/PROTECTION MYFILE.TXT 
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Example 5-1 illustrates some file manipulation commands. 



1 $ DIRECTORY 



Directory DISK: [SMITH] 

CLASS. LIST; 4 CLOCK.EXE; 1 
JOE_EVE . TPU$SECTION; 1 
MYFILE.TXT; 1 NOTE.COM 
TRNG.PLAN;6 VT100.CLR;1 

Total of 13 files. 



COLOR.COM; 4 
MYFILE.TXT; 3 
REMIND.EXE;! 



DEC EXE ;1 
MYFILE.TXT; 2 
REMLOG.EXE;! 



$ CREATE FILE1.TXT 

From the time when man first began making numerical calculations, 

he has been inventing devices to aid him in the handling of 

numbers . These devices have been particularly useful where the 

calculations have been repetitive. With the advent of the modern 

computer, more and more control has been given to the machine 

to reduce the repetition and thus the possibility of human error. 

CTRL/Z 

$ CREATE FILE2.TXT 

From the time when man first began making numerical calculations, 

he has been inventing devices to aid him in the handling of 

numbers. These devices have been particularly helpful when the 

calculations have been repetitive. With the advent of the modern 

computer, more and more control has been given to the machine 

to reduce the repetition and therefore the possibility of human error. 

CTRL/Z 

$ APPEND/LOG MYFILE.TXT TRNG.PLAN 

%APPEND-S -APPENDED, DISK: [ SMITH] MYFILE .TXT; 1 appended to 

DISK: [SMITH] TRNG.PLAN; 6 (6 records) 

$ PURGE /LOG MYFILE.TXT 

%PURGE-I-FILPURG, DISK: [SMITH] MYFILE. TXT;2 deleted (4 blocks) 

%PURGE-I-FILPURG, DISK: [SMITH] MYFILE. TXT; 1 deleted (4 blocks) 

$ DELETE/LOG MYFILE. TXT; 3 

%DELETE-I-FILDEL, DISK: [ SMITH] MYFILE . TXT; 3 deleted (3 blocks) 



Example 5-1 Using VMS Commands to Maintain Your Default Directory 
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Notes on Example 5-1: 

In Example 5-1, assume you are the user who issues the commands. Your default 
directory is [SMITH]. 

1 $ DIRECTORY 

To list the files in your default directory use the DIRECTORY command. The 
first line of output displayed at your terminal, directory DISK: [SMITH], reports 
the name and location of your default directory. The remaining lines list the names 
of the files it catalogs. 

2 $ CREATE FILE1 . TXT 
$ CREATE FILE2.TXT 

You can create additional files in your directory at any time. This module only 
uses the CREATE command for cataloging text files in your directory file. You 
can use the DCL line-editing commands discussed in the Getting Started module 
to format each line you enter with the CREATE command. Pressing CTRL/Z 
ends file input. 

Several text editor utilities are available on the VMS system. Text editors are 
discussed in the Creating and Editing Text Files module. 

3 $ APPEND/LOG MYFILE.TXT TRNG.PLAN 

To concatenate MYFILE.TXT with TRNG.PLAN, enter the APPEND command, 
followed by the name of the file you want to append (MYFILE.TXT), followed by 
the name of the file you want to append it to (TRNG.PLAN). This operation does 
not create any new files. The contents of TRNG.PLAN are modified to include 
the file MYFILE.TXT. The contents of MYFILE.TXT are unaffected. To instruct 
the system to display a message when it completes the operation, add the /LOG 
qualifier to the APPEND command. 

4 $ P URGE /LOG MYF ILE . TXT 

Since your default directory contains multiple versions of MYFILE.TXT, you can 
delete all but the most recent version. To do so, enter the PURGE command. To 
display the name of each file the system deletes, append the /LOG qualifier. 

5 $ DELETE /LOG MYF ILE. TXT; 3 

You decide that you no longer need the contents of MYFILE.TXT. To delete the 
remaining MYFILE.TXT from your directory, enter the DELETE command. By 
specifying the version number 3, you delete only that version of the file. Any 
other versions of the file would remain in your directory. 
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Example 5-2 illustrates how to use VMS commands to compare two files and find their 
differences. In this example, you compare the files FILE1.TXT and FILE2.TXT that 
you created in Example 5-1. 

$ TYPE FILE1.TXT 

From the time when man first began making numerical calculations, 

he has been inventing devices to aid him in the handling of 

numbers . These devices have been particularly useful where the 

calculations have been repetitive. With the advent of the modern 

computer, more and more control has been given to the machine 

to reduce the repetition and thus the possibility of human error. 

$ TYPE FILE2.TXT 

From the time when man first began making numerical calculations, 

he has been inventing devices to aid him in the handling of 

numbers . These devices have been particularly helpful when the 

calculations have been repetitive. With the advancement of the modern 

computer, greater control has been given to the machine 

to reduce the repetition and therefore the possibility of human error. 

$ DIFFERENCES FILE1.TXT FILE2 .TXT/CHANGE_BAR= : 
************ 

File DISK: [ SMITH] FILE2 . TXT; 1 

1 From the time when man first began making numerical calculations, 

2 he has been inventing devices to aid him in the handling of 

3 : numbers. These devices have been particularly helpful when the 

4 : calculations have been repetitive. With the advancement of the modern 

5 : computer, greater control has been given to the machine 

6 : to reduce the repetition and therefore the possibility of human error. 
************ 

Number of difference sections found: 1 
Number of difference records found: 4 

DIFFERENCES /IGNORE=()- 

DISK: [ SMITH] FILE1. TXT; 1- 

DISK: [SMITH] FILE2. TXT; 1/CHANGE BAR= ( " : " ) 



Example 5-2 Comparing Files 
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Notes on Example 5-2: 

1 $ TYPE FILE1.TXT 
$ TYPE FILE2.TXT 

Before comparing FHJE1.TXT with FELE2.TXT, you decide to display the contents 
at your terminal. To do so, enter the TYPE command. 

2 $ DIFFERENCES FILE1.TXT FILE2 . TXT/CRANGE_BAR=: 

You want to compare FILE1.TXT with FILE2.TXT to determine how they differ. 
You have already displayed the contents of both files. You would like to display 
FUJE2.TXT with the lines that differ marked in an appropriate way (with a colon, 
for example). To do this, enter the DIFFERENCES command followed by the 
specifications of the files you want to compare. To generate a marked listing of 
FILE2.TXT, specify that file last. Terminate the specification of the file with the 
/CHANGE_BAR qualifier. Following a heading, the system displays the contents 
of the second file at your terminal. A colon precedes each line that differs from 
the first file. 
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5.8.1 Using Wildcards in File Specifications 

At times it is useful to specify a group of files that have parts of a file specification in 
common. For example, you may want to delete all the files of a given file type in your 
default directory. Wildcards allow this. Table 5-7 describes wildcard symbols that you 
can use in the name, type, and version fields of a file specification. 

Wildcards are also used: 

• To abbreviate a file specification 

To specifically match one character in file names or file types 
In conjunction with each other or separately 



Table 5-7 Wildcards Used to Specify File Names, Types, and Versions 

Symbol Meaning 

* Asterisk Match 0-39 characters in a file name, file type, or version 

number 

% Percent Match exactly one character in a file name or file type 
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Example 5-3 illustrates the directory named [SMITH], which contains eight files. 
Table 5-8 selectively refers to these files, using wildcard characters. 



Directory W0RK2 : [SMITH] 



PAY . FOR; 2 
PAYOFF. FOR; 3 

Total of 8 files. 



PAY.FOR;l 
PROBLEMS . TXT ; 4 



PAY1.FOR;! 
REPORT. MEM; 9 



PAY2.FOR;14 
REPORT.RNO;6 



Example 5-3 A Sample Directory File 



Table 5-8 Using Wildcards to Specify Files 



Directory 
Specification 



Description 



Corresponding Files 



$ directory pay. FOR; * All versions of PAY.FOR 



PAY.FOR;2 
PAY.FOR;! 



$ DIRECTORY *.*;! 



$ DIRECTORY *.*;* 



All files with a version 
number of 1 

All files, types, and 



versions 



PAY.FOR; 1 
PAYl.FOR;l 

All files in the directory 



$ DIRECTORY PAY%.FOR;* 



All versions of files with 
file types of FOR and 
file names beginning with 
PAY, followed by exactly 
one character 



PAYl.FOR;l 
PAY2.FOR;14 



$ DIRECTORY PAY*.*;* 



All files whose first three PAYl.FOR;l 
letters are PAY, including PAY.FOR;2 
all file types and all PAYFOR;l 

versions PAYOFF.FOR;3 

PAY2.FOR;14 



'Issuing the DIRECTORY command with no qualifiers or wildcards lists all files, types, and versions by 
default. 
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5.9 ORGANIZING YOUR DIRECTORY STRUCTURE 

In addition to your master file directory and user file directories, you can also have 
subdirectories. Subdirectories are used to better organize the directory structure, to 
protect files from accidental modification or loss, and to decrease the time for the system 
to find files. 

Each UFD can have a maximum of seven levels of subdirectories below it. Each 
directory level has a level identifier of 1-39 characters that makes up part of the directory 
name. 

Files are usually grouped by: 

Function (all command files) 
Application (all files for a given project) 
Type (all FORTRAN files) 

Subdirectories can catalog other subdirectories as well as files. Table 5-9 shows the 
three levels of directories and conventions for naming them. 
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5,9.1 Directory Names in the Hierarchy 



Table 5-9 Directory Names 



Directory Type 



Example 



Master File Directory (MFD) [000000] 



User File Directory (UFD) [SMITH] 



Subdirectory (SFD) 



[SMrTHJDOC] 



Naming Convention 



Each disk contains one MFD, 
named [000000], which is given 
by the system. 

The owner's user name is 
usually the Level 1 directory 
name. 

The subdirectory name includes 
the directory name where it is 
created. Each subdirectory name 
is separated by a period. 



The ability to create and maintain a subdirectory structure starting with your UFD is a 
powerful tool in organizing your files. To create and maintain a subdirectory hierarchy, 
you should be able to perform the following operations: 

Create subdirectories 

Move around in the directory hierarchy 

Display a hierarchy and its contents at your terminal 

Determine the name of your current default directory or subdirectory 

Move files from one directory to another 

Assign a protection code to a subdirectory 

Remove a subdirectory from the hierarchy 

The following pages show you how to do this. You can also refer to Table 5-5 for more 
examples of how to manipulate files in your default directory. 
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5.9.2 Creating a Subdirectory 

To create a subdirectory, use the CREATE/DIRECTORY command in the format: 
$ CREATE/DIRECTORY [directory.subdirectory] 

The subdirectory name must be enclosed in brackets 

• The subdirectory name includes the directory name where it is created 

• Separate subdirectory names with a period 
The directory or subdirectory itself is a file 

— The directory or subdirectory has a file type of DIR 

— The version number of file type DIR is 1 

Example: 

$ CREATE/DIRECTORY/LOG [SMITH.DOC] 

(System response:) 

%CREATE-I-CREATED DISK: [SMITH .DOC] created 

The directory [SMITH] is a Level 1 directory 

The subdirectory [.DOC] is the next level below the directory [SMITH] 

The /LOG qualifier displays, at your terminal, the fact that the subdirectory was 
created 

To create another subdirectory beneath the [.DOC] subdirectory, use the following 
command format: 

$ CREATE/DIRECTORY [directory.subdirectory.subdirectory] 
Example: 

$ CREATE /DIRECTORY/LOG [SMITH.DOC. FORTRAN] 
%CREATE-I-CREATED DISK: [SMITH.DOC. FORTRAN] created 

The subdirectory [.FORTRAN] is now listed under the subdirectory [SMITH.DOC] 
Figure 5-2 illustrates four levels of directories in a hierarchy. 
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DIRECTORY NAME 

MASTER FILE DIRECTORY 
[OOOOOD] 



USER FILE DIRECTORY 
[SMITH] 



SUBDIRECTORY 
[SMITH. PROJ] 



SUBDIRECTORY 
[SMITH. PROJ. LAB] 



FILES CONTAINED 



USER1.DIR 



USER2.DIR 




SMITH. DIR 



LOGIN.COM 



MAIL. MAI 




PROJ. DIR 



MOD. DIR 



NOTE. TXT 




LAB. DIR 



MON.TXT 



TUE.TXT 



© 



COMMENTS 

THE MASTER FILE DIRECTORY 
(MFD) CATALOGS THE FILES 
THAT IMPLEMENT THE USER 
FILE DIRECTORIES. 



THE USER FILE DIRECTORY (UFD) 
CATALOGS FILES. NOTE THAT 
PROJ. DIR IMPLEMENTS THE 
SUBDIRECTORY [SMITH. PROJ). 



THE SUB FILE DIRECTORY 

(SFD) [SMITH. PROJ] 

IS A LEVEL 2 DIRECTORY. 



SFD [SMITH. PROJ. LAB] 
IS A LEVEL 3 DIRECTORY. 
LEVEL 8 IS THE MAXIMUM 
DIRECTORY LEVEL. 



(J) [000000] SMITH. DIR @ [SMITH. PROJ]LAB. DIR 

(T) [SMITH] PROJ. DIR (V) [SMITH. PROJ. LAB]MON.TXT 



TTB X0328_88 



Figure 5-2 File Specification in the Directory Hierarchy 
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5. 10 MOVING WITHIN A DIRECTORY HIERARCHY 

There are three characters used to move within a directory hierarchy. They are: 

Hyphen (-) 
Period (.) 
Ellipsis (...) 

The hyphen and period characters are normally used in conjunction with the SET 
DEFAULT command to move from your current directory to another directory or 
subdirectory. 

The ellipsis character can be used with the DIRECTORY command to list files in a 
directory and all subdirectories beneath it (see Example 5-^J). Table 5-10 describes 
these three characters. 



Table 5-10 Characters Used to Specify Directories 



Symbol Meaning 



- (hyphen) Move one level up in directory hierarchy 

. (period) Move one level down in directory hierarchy (MUST be 

followed by a subdirectory name) 

... (ellipsis) Use current directory and all directories below it 
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5.10.1 using the oca ui^rj^ui^x wuimudnu 

The DCL command SET DEFAULT changes the default device and/or the directory 
name for your current process. 

A physical device name MUST be terminated with a colon (:) 

A directory or subdirectory name MUST be enclosed in square brackets 

The syntax for the SET DEFAULT command is: 

$ SET DEFAULT device-name: [directory-name] 

or 

$ SET DEFAULT [directory-name.subdirectory-name] 

Examples of its use: 

$ SET DEFAULT [SMITH.DOC] 

$ SET DEFAULT DISK2 : [SMITH. FOR] 

In the first example, the device name remains the same, and in the second example, the 
device name and directory name change. 

5.10.2 Using the SHOW DEFAULT Command 

The DCL command SHOW DEFAULT displays your current default device and 
directory names. 

Examples: 

$ SHOW DEFAULT 

DISK: [SMITH] 
$ SET DEFAULT [SMITH.DOC] 
$ SHOW DEFAULT 

DISK: [SMITH.DOC] 
$ SET DEFAULT [-] 
$ SHOW DEFAULT 

DISK: [SMITH] 
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5.10.3 Using the COPY and RENAME Commands 

At times you will need to move files from one directory to another. For example, you 
may want to catalogue the files in your default directory by job or type. You could 
copy all the files with a BAS extension into a subdirectory called BASIC (assuming the 
BASIC subdirectory already exists). You would do this by using the COPY command 
with the directory and file specifications you want to copy from and to. If your default 
directory name is SMITH, the command would look like this: 

$ COPY [SMITH]*. BAS [SMITH. BASIC] *.*; * 

Table 5-11 gives additional examples of moving files from one directory to another. 



Table 5-11 Commands to Move Files Within a Directory Hierarchy 



Operation 



Move files from one 
directory or subdirectory 
to another 



Copy files from one 
directory or subdirectory 
to another 



Comments 



Moves the most recent version of all files with the file 
type FOR from the directory [SMITH] to the subdirectory 
[SMITH.FORTRAN] 

$ RENAME [SMITH]*. FOR [SMITH.FORTRAN] * .FOR 

Copies all versions of files with the file type PAS 
from the [SMITH.UTLCOM] subdirectory to the 
[SMITH.UTLCOM.PASCAL] subdirectory 

$ COPY [SMITH.UTLCOM]*. PAS;* - 
[SMITH.UTLCOM.PASCAL]*.*;* 
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Example 5-4 shows you how to create two levels of subdirectories under the UFD 
[SMITH] and how to move files into one of the subdirectories. See the notes to the 
example for a detailed explanation. 

1 $ SHOW DEFAULT 

DISK: [SMITH] 

2 $ CREATE/DIRECTORY/LOG [SMITH.COM] 
%CREATE-I-CREATED, DISK: [SMITH. COM] created 
$ CREATE/DIRECTORY/LOG [ SMITH. DTLC0M] 
%CREATE- I -CREATED, DISK: [SMITH. DTLC0M] created 
$ CREATE/DIRECTORY/LOG [ .UTLCOM.FIL] 
%CREATE-I-CREATED, DISK: [SMITH. UTLCOM.FIL] created 
$ CREATE/DIRECTORY/LOG [ .UTLCOM.EDT] 

%CREATE- I -CREATED, DISK: [SMITH. UTLCOM.EDT] created 

3 $ DIRECTORY [ . . . ] 

4 Directory DISK: [SMITH] 

C0M.DIR;1 F0RCALL.MAR;1 MMUL.F0R;1 POLA QU0-1 

PRINT. F0R;1 RANDOM. FOR; 1 STRPR0G.TXT; 1 UTLCOM.DIR;l 

Total of 8 files. 

Directory DISK: [ SMITH. UTLCOM] 

EDT.DIR;1 FIL.DIR;1 

Total of 2 files. 

Grand total of 2 directories, 10 files. 

5 S'RENAME [SMITH] * .MAR, *. TXT [.UTLCOM.FIL]*.* 
$ SET DEFAULT [.UTLCOM.FIL] 

$ DIRECTORY 

Directory DISK: [SMITH. UTLCOM.FIL] 
FORCALL -MAR; 1 STRPROG . TXT ; 1 

Total of 2 files. 

Example 5-4 Using VMS Commands to Create and Maintain a Directory Hierarchy 
Notes on Example 5-4: 

1 $ SHOW DEFAULT 

Before creating a subdirectory hierarchy, you need to know the name of your 
current default device and directory. To display this information, enter the SHOW 
DEFAULT command. Your default device is DISK. Your default directory is 
named SMITH. 
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2 $ CREATE/DIRECTORY/LOu [SMITH.COM] 
%CREATE-I-CREATED, DISK: [SMITH.UTLCOM.EDT] created 

To create subdirectories, issue the CREATE/DIRECTORY command at your 
terminal, followed by a directory name. 

By including the /LOG qualifier in each CREATE/DIRECTORY command 
string, you instruct the system to display a message at your terminal each time it 
successfully creates a subdirectory file. 

3 $ DIRECTORY [ . . . ] 

Once you create a hierarchy of subdirectories, display your work by entering a 
DIRECTORY command string. Use an ellipsis (...) in the directory specification 
to force a search of all subdirectories associated with your UFD. No UFD name is 
required in the directory specification, since your default directory name is equated 
to its value. 

4 Directory DISK: [SMITH] 

The display produced by the DIRECTORY command reveals the skeleton of the 
hierarchy you have created. At the top of the structure is your UFD, SMITH, 
which now lists two directory files, COM.DIR and UTLCOM.DIR, in addition to 
other files. 

The target subdirectories named COM and UTLCOM form the next level of your 
hierarchy. COM contains no files. UTLCOM, however, lists two directory files, 
EDT.DER. and FIL.DIR. These two subdirectories form the third level of your 
hierarchy. 

5 $ RENAME [SMITH] *. MAR, *. TXT, [ -DTLCOM.FIL] * . * 
$ SET DEFAULT [ .DTLCOM.FIL] 

$ DIRECTORY 

To change which directory catalogues a file, use the RENAME command, hi this 
example, you choose to recatalogue all the most recent versions of files in the 
directory named [SMITH] with file types MAR and TXT to the directory named 
[.UTLCOM.FIL], retaining the same file name, file type, and version number. 

Notice that the command that alters which directory catalogues a file is the 
RENAME command and not the COPY command. Use the RENAME command 
when all the files reside on the same disk structure. To move files from one disk 
structure to another, use the COPY command. 

To see files that were renamed to the subdirectory FIL, set your default to 
[.UTLCOM.FIL] and issue a DIRECTORY command. 
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5. 1 1 PROTECTING FILES IN YOUR DIRECTORY HIERARCHY 

Hie VMS system allows you to access other users' files. To create a file in your 
directory with the contents of a file that exists in another user's directory, include 
the other user's directory name in the file specification when you enter the COPY 
command. For example: 

$ COPY [MATTHEWS] WANTED. FIL NEW.FIL 

The system places a copy of the text found in the file WANTED.FTL of the directory 
named [MATTHEWS] into your default directory, giving it the name NEW.FIL. 

Since it is possible for users to manipulate the files of others, it is necessary to protect 
files from unwanted access. To access a disk file, a user must pass the following three 
levels of protection: 

Volume protection — Controls who can access a particular disk volume 
Directory protection — Controls who can access a particular directory 
File protection — Controls who can access a particular file 

To access a tape volume, a user only needs to pass the volume level of protection, 
which controls who can manipulate files on tapes. 
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5.11.1 How the System Determines Access 

When you attempt to access a file, your UIC is compared to the owner UIC of the 
file. Depending on the relationship of the UICs, you will fall into one or more of the 
following categories. 

SYSTEM— All users who have system privilege (SYSPRV) or low group numbers, 
usually from 1 through 10 (octal). 

OWNER — The user with the same UIC as the owner UIC of the file. 

GROUP — All users, including the owner, who have the same group number in 
their UICs as the file owner. 

WORLD — All users, including those in the first three categories. 

The protection code describes the categories of users who have access to a file, and the 
type of access they have. For example, the protection code: 

SYSTEM :RWED, OWNER :RWED, GROUP: RE, WORLD: RE 

specifies that users in the SYSTEM and OWNER categories have READ, WRITE, 
EXECUTE, and DELETE access. Users in the GROUP and WORLD categories have 
only READ and EXECUTE access. 

Figures 5-3 and 5-4 illustrate protection codes. Also, see Tables 5-12 and 5-13 for an 
explanation of access rights and user categories. 
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GROUP 

[owner] 



WORLD 



(system) 



TTB X033O B8 



Figure 5-3 Interaction of Access Categories 

PROTECTION CODE 



PROTECTION CODE 
DELIMITER 



USER CATEGORY 
SYMBOL (SYSTEM) 



r 



~\ 



(S:RWED, 0:RWED,G:RE,W) 



USER CATEGORY 
DELIMITER 



USER CATEGORY 
ACCESS CODES (READ, 
WRITE, EXECUTE 
AND DELETE) 



USER CATEGORY 
SEPARATOR 



J 
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Figure 5-4 Elements of a Protection Code: Determines Which Users Have Access to a File 
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Table 5-12 


Summary of Effects of Access Rights to Files 






(R)ead 


(W)rite (E)xecute 


(D)elete 


Disk 
Directory 


Can read list 
of files in 
directory 


Can modify Can access 
list explicitly 
(Add files) named files 
Read access 
also needed 


Can delete the 
directory 


Disk File 


Can read 
contents of 
file(s) 


Can modify Can execute 
contents of executable files 
file(s) 


Can delete file(s) 


Tape File 


Can read list of 
files on tape 


Can add files Does not apply 
on the volume 


Does not apply 





Table 5-13 Determining a User's Category by Comparing User's UIC to File 
Owner's UIC 



Category Group Number 



Member Number 



SYSTEM 0-10 (Octal) 



Does not matter 



OWNER Matches group number of file UIC Matches member number of file 

UIC 

GROUP Matches group number of file UIC Does not matter 

WORLD Does not matter Does not matter 
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5.12 PROTECTION MECHANISMS 

The VMS system uses the following two protection mechanisms: 

Access control lists (an optional protection) 

• UlC-based protection 

In granting access to a device or file, the VMS system checks the associated access 
control list (ACL) followed by the UlC-based protection. If the ACL allows access, 
then the UlC-based protection is not checked. If the ACL denies access, the system 
checks only the system and owner fields of the UlC-based protection code to determine 
whether you have access. If there is no ACL or you are not mentioned in the ACL, then 
the UlC-based protection is checked to determine access rights. Therefore, ACLs allow 
you to add limitations to the protection already provided by the UlC-based protection. 

5.12.1 UIC-Based Protection 

The VMS system assigns each file a UIC and a protection code when it is created. The 
system uses the UIC and protection code to determine who can: 

• Read the file 

• Modify the file 
Execute the file 
Delete the file 

The format of your UIC is a pair of numbers in brackets, as follows: 

[group,member] 

The group number can range from to 37777 (octal), while there can be from to 
177777 (octal) members in each group. 

Examples: 

Numeric: [100,30] 

Alphanumeric: [GROUP11, SMITH] or [SMITH] 

UICs specify the owners of objects, such as files, for which the VMS system provides 
protection. A user attempting to access a file falls into one of four access categories: 
System, Owner, Group, or World. The system places the user in a particular category by 
comparing the user's UIC to the UIC attribute of the file. The system manager assigns 
UICs. 
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Suppose a file has the following protection code: 

S:R,0:R,G:R,W:RWED 

You might expect that the owner would have only read access to the file. However, a 
user may be granted access to a file through more than one category. Any user in the 
Owner Category is also in the Group and World Categories. Therefore, the owner has 
read, write, execute, and delete access. The usual default protection codes supplied by 
the system are: 

File S:RWED,0:RWED,G:RE,W 

Directory S:RWE,0:RWE,G:RE,W 
Volume S:RWED,0:RWED,G:RWED,W:RWED 

To alter the protection of files, you must have a system UIC, SYSPRV privilege, or own 
the file. 
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5.12.2 Access Control Lists 

Access control lists are an optional layer of protection normally specified by the system 
manager. They are used to obtain more control than UlC-based protection. ACLs are 
usually used to provide access for specific users but not all users on the system. 

Identifiers are the means of specifying the users in an ACL. There are three types of 
identifiers: 

1. UIC identifiers that depend on the user identification codes (UICs) that uniquely 
identify each user on the system. 

2. General identifiers that are defined by the system manager to identify groups of 
users (for example, STUDENT or PERSONNEL). 

3. System-defined identifiers that describe certain types of users (BATCH, NETWORK, 
LOCAL, REMOTE). These identifiers are automatically defined by the system at 
installation time. 

Users can have one or more identifiers. Files specify the access rights for holders of 
various identifiers. Since there may be many identifiers needed to represent different 
access needs for each user, you may need to create a list of entries, each of which 
defines groups of access rights. This list is the access control list (ACL). Each entry in 
this list is called an access control list entry (ACE). 

5.12.3 Creating or Modifying an Access Control List 

The following commands are used to obtain ACL information: 

SHOW ACL file-name 
DIRECTORY/ ACL file-name 
• DIRECTORY/FULL file-name 

DIRECTORY/SECURITY file-name 
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5,12,3.1 Access Control List Entries 

Each AOL consists of one or more ACEs. There is no limit to the number of ACEs 
that an ACL can have, or to the number of characters in an ACE. You can add ACEs to 
your ACL by using the DCL command EDIT/ ACL file-name, which invokes the ACL 
editor. 

The format for an ACE is: 

(TYPE,[OPTIONS],[ACCESS]) 

The first field, TYPE, determines the type of access protection. There are three types of 
ACEs: 

1. Identifier — Controls the type of access allowed to a particular user or group of 
users 

The first field in the identifier ACE consists of the keyword IDENTIFIER followed 
by one or more identifiers. An identifier can be: 

The user identification code (UIC) 

• A general identifier established by the system manager 

• A system-defined identifier 

2. Default Protection — Defines the default protection for a directory 

3. Security Alarm — Provides a security alarm when an object (such as a file or 
directory) is accessed in a particular way 

The second field, OPTIONS, indicates options (if any) that apply to the ACE. 

The third field, ACCESS, indicates the type of access to be granted to the file, such as 
READ, WRITE, EXECUTE, or DELETE. 

The exact format of an ACE depends on its type, but all ACEs are enclosed 
in parentheses. Example 5-5 shows you how to modify the ACL for the file 
MYFDLE.TXT. 
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S DIRECTORY/FDLL MYFILE.TXT 

Directory DISK: [SMITH] 

MYFILE.TXT;! File ID: 

Size: 1/3 Owner: 

Created: 17-DEC-1986 14:18 Revised: 

Expires: <None specif ied> Backup: 



(25168,6,0) 
[GROUP 11, SMITH] 
17-DEC-1986 14:24 (3) 
<No backup recorded> 



File organization: 
File attributes : 

Record format : 
Record attributes : 
Journaling enabled: 
File protection: 
Access Cntrl List: 



Sequential 

Allocation: 3, Extend: 0, Global buffer count: 0, 

No version limit 

Variable length, maximum 4 7 bytes 

Carriage return carriage control 

None 

System: RWED, Owner :RWED, Group: RE, World: 

None 



Total of 1 file, 1/3 blocks. 

$ EDIT/ACL MYFILE.TXT 

( IDENTIFIER=VMS , ACCESS=READ+WRITE+EXECUTE+DELETE ) 
CTRL/Z 

$ DIRECTORY/ FOLL MYFILE.TXT 

Directory DISK: [SMITH] 



MYFILE.TXT; 1 

Size: 

Created: 17-DEC 

Expires: <None 

File organization 

File attributes : 

Record format : 
Record attributes 
Journaling enable 
File protection: 
Access Cntrl List 



File ID: 
1/3 Owner: 

1986 14:18 Revised: 
specif ied> Backup : 

Sequential 

Allocation: 3, Extend: 

No version limit 

Variable length, maximum 47 bytes 

Carriage return carriage control 
d: None 

System:RWED, Owner:RWED, Group:RE, World: 

(IDENTIFIER=VMS,ACCESS=READ+WRITE+EXECUTE+DELETE) 



(25168,6,0) 
[GROOP11, SMITH] 
17-DEC-1986 14:45 (4) 
<No backup recorded> 



0, Global buffer count: 0, 



Total of 1 file, 1/3 blocks. 



Example 5-5 Modifying an Access Control List 
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5.13 DETERMINING AND ALTERING FILE PROTECTION 

Each file on a disk has its own protection code. You can determine the current default 
protection by issuing the SHOW PROTECTION command: 

$ SHOW PROTECTION 

SYSTEM=RWED, OWNER=RWED, GROUP=RE, WORLD=NO ACCESS 

This response is your default protection. To determine the current protection on a specific 
file or files, use the /PROTECTION qualifier with the DIRECTORY command. For 
example: 

$ DIRECTORY/PROTECTION DIRECTORY. LIS 

Directory DISK: [SMITH. DOC] 

DIRECT0RY.LIS;1 [100,200] (RWED, RWED,RE, > 

You can set the protection when you create a file or change the protection on an 
existing file using the SET PROTECTION command. For example, you can specify 
the protection for a file you create using the COPY command as follows: 

$ COPY DISK1: t SMITH] DIRECTORY. LIS 

DIR.LIS/PROTECTION= (SYSTEM: RW, OWNER: RWED, GROUP :RW, WORLD) 

This command copies a file from the device DISK1 to your default disk directory. The 
protection code defines the protection for the new file DIR.LIS as: 

• Users with system UICs can read and write to the file 
You (owner) have all types of access 

Other users in your group can read and write to the file 

• All other users (world) have no access 
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If you do not define a protection code for a file when you create it, the system applies 
a default protection. If a version of the file already exists, protection is taken from the 
previous version. For a new file, the protection is determined in one of two ways: 

1. If the directory where the file is to be placed has an associated access control list 
that specifies the DEFAULT_PROTECTION entry, the specified protection is used. 

2. If the directory does not have an associated ACL, the default process protection 
is used. The default process protection is established explicitly with the SET 
PROTECTION/DEFAULT command, or by default when you log in. See 
Table 5-14 and Example 5-6 for more information on setting protections. 

NOTE 

To protect a file completely, you must protect both the file itself and the 
directory in which the file is listed. If you have files that must be protected 
against unauthorized access, be sure to specify the proper protection for both 
the directories and the files themselves. 
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Table 5— 14 Commands Used to Determine and Alter File Protection 



Operation 



Comments and Examples 



Displaying the 
default protection 
assigned to 
new files 

Obtaining the 
protection code 
of a given file 

Changing the 
default protection 
assigned to new 
files 



Changing the 
protection code of 
an existing file 



The default protection applies to all newly created files in the 
current directory 

$ SHOW PROTECTION 

Displays the current protection of a particular file 

$ DIRECTORY/PROTECTION MYFILE.TXT 

The default protection, once changed, affects all future files 
created in this particular directory. Files created before changing 
the default protection will retain the previous protection. 

$ SET PROTECTION=(S:RWED,0:RWED,G:RWE,W:RWE)/DEFAULT 

The protection code can be changed to allow more or less access 
to a particular file. 

$ SET PROTECTION=(S:RWED,0:RWE,G:RW, W: ) MYFILE.TXT 



NOTE 

If you omit a protection category when you issue the SET PROTECTION 

command, the protection for that category remains unchanged. 
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$ SET DEFAULT [SMITH.DOC] 

$ SHOW PROTECTION 

SYSTEM=RWED, OWNER=RWED, GROUP=RE, WORLD=NO ACCESS 

$ DIRECTORY/OUTPUT=DIRECTORY.LIS 
$ DIRECTORY/OWNER/PROTECTION 

Directory DISK: [SMITH.DOC] 

DIRECTORY. LIS; 1 [GROUP 11, SMITH] (RWED, RWED, RE, ) 
EDT.DIR;1 [GROUP 11, SMITH] (RWE, RWE, RWE, RE) 

Total of 1 file. 

$ SET PROTECTION (S:R,G:R) /DEFAULT 

$ SHOW PROTECTION 

SYSTEM=R, OWNER=RWED, GROUP=R, WORLD=NO ACCESS 

$ DIRECTORY/OUTPUT=DIRECTORY.LIS 
$ DIRECTORY/OWNER/PROTECTION 

Directory DISK: [SMITH.DOC] 

DIRECTORY. LIS; 2 [GROUP 11, SMITH] (R,RWED,R, ) 
DIRECTORY. LIS; 1 [GROUP 11, SMITH] (RWED, RWED, RE, ) 
EDT.DIR;1 [GROUP 11, SMITH] (RWE, RWE, RWE, RE) 

Total of 2 files. 



Example 5-6 Changing Your Default Protection Code 
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5.14 DELETING A SUBDIRECTORY 

Before you can delete a subdirectory, you must delete all the files catalogued in that 
subdirectory. When all the files have been deleted, set your default to the directory or 
subdirectory that contains the subdirectory name to be deleted. The directory protection 
on the subdirectory to be deleted must allow the owner DELETE access. If it does not, 
you must change the directory protection to reflect this. Example 5-7 shows how to 
delete a subdirectory from a directory, and Example 5-8 shows how to delete two levels 
of subdirectories. 

$ SET DEFAULT [SMITH.DOC] 
$ DIRECTORY 

Directory DISK: [SMITH.DOC] 

CLASS. LIST;4 CLOCK. EXE;1 COLOR. C0M;4 DEG.EXE;1 
JOE_EVE.TPU$SECTION;l MYFILE.TXT; 1 NOTE. COM; 4 

REMIND. EXE;1 REMLOG . EXE ; 1 TRNG.PLAN;6 VT100.CLR;1 

Total of 11 files. 

$ DELETE *.*;* 
$ DIRECTORY 

%DIRECT-W-NOFILES, no files found 

$ SET DEFAULT [SMITH] 

$ DELETE DOC.DIR;l 

%DELETE-W-FILNOTDEL, error deleting DISK: [SMITH] DOC. DIR;1 
-RMS-E-PRV, insufficient privilege or file protection violation 

$ SET PROTECTION=(0:RWED) DOC.DIR 

$ DELETE DOC.DIR; 1 

$ DIRECTORY DOC.DIR 

%DIRECT-W-FILES, no files found 

Example 5-7 Deleting a Subdirectory from a Directory Hierarchy 
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1 $ SET DEFAULT [SMITH] 

2 $ DIRECTORY [SMITH...] 
Directory DISK: [SMITH] 

DOC.DIR;! MYF ILE . TXT ; 1 MYTEXT . TXT ; 1 TXT. TXT; 1 
Total of 4 files. 

Directory DISK: [SMITH.DOC] 

FORTRAN. DIR;1 MYF ILE . TXT ; 1 MYTEXT . TXT ; 1 TXT.TXT;1 

YOOR.FILE/1 

Total of 5 files. 

Directory DISK: [SMITH. DOC. FORTRAN] 

MYF ILE. TXT ;1 MYTEXT . TXT ; 1 TXT. TXT ;1 YOUR. FILE ; 1 

Total of 4 files. 

Grand total of 3 directories, 13 files. 

3 $ SET PROTECTIONS .-RWED [SMITH...]*.*;* 

4 $ DELETE [SMITH...]*.*;* 

%DELETE-W-FILNOTDEL, error deleting DISK: [SMITH] DOC.DIR; 1 
-RMS-E-MKD, ACP could not mark file for deletion 
-SYSTEM-F-DIRNOTEMPTY, directory file is not empty 
%DELETE-W-FILNOTDEL, error deleting DISK: [SMITH] FORTRAN. DIR; 1 
-RMS-E-MKD, ACP could not mark file for deletion 
-SYSTEM-F-DIRNOTEMPTY, directory file is not empty 

5 $ DIRECTORY [SMITH...] 
Directory DISK: [SMITH] 
DOC.DIR; 1 

Total of 1 file. 

Directory DISK: [SMITH.DOC] 
FORTRAN. DIR; 1 
Total of 1 file. 

Grand total of 2 directories, 2 files. 

6 $ DELETE [ SMITH ...]*.*;* 

%DELETE-W-FILNOTDEL, error deleting DISK: [SMITH] DOC.DIR; 1 
-RMS-E-MKD, ACP could not mark file for deletion 
-SYSTEM-F-DIRNOTEMPTY, directory file is not empty 

7 $ DIRECTORY [SMITH...] 
Directory DISK: [SMITH] 
DOC.DIR; 1 

Total of 1 file. 

8 $ DELETE [ SMITH ...]*.*;* 
$ DIRECTORY [SMITH...] 
%DIRECT-W-NOFILES, no files found 

Example 5-8 Removing Subdirectories from a Directory Hierarchy 
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Notes on Example 5-8: 

1 The SET DEFAULT command moves the user to a Level 1 directory. 

2 The DIRECTORY command is issued to obtain a listing of all files in the directory 
hierarchy. 

3 Protection is set to enable the owner to delete all files and all subdirectories. 

4 The DELETE command is issued to delete all files and all subdirectories. The 
subdirectories (DOC.DIR and FORTRAN.DIR) are not deleted during the first 
issuance of the DELETE command. A fatal error message is generated: "directory 
file is not empty." 

5 The DIRECTORY command is issued, which establishes that all files have been 
deleted except the subdirectories DOC.DIR and FORTRAN.DIR. 

6 The DELETE command is re-issued. This deletes the subdirectory [.FORTRAN] 
but the subdirectory [.DOC] is not deleted. A fatal error message is generated: 
"directory file is not empty." 

7 The DIRECTORY command is issued, which establishes that the subdirectory 
DOC.DIR has not yet been deleted. 

8 The DELETE command is issued again and now the subdirectory [.DOC] is 
deleted. 

NOTE 

Issuing the DIRECTORY command is an optional step. In this example, it 

is showing the remaining files during each step in the process of deleting 

subdirectories. 
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5.15 SPECIFYING DEVICES 



DEVICE SPECIFICATION 




VAX DEVICES 



TTB_X0332_88_S 



Figure 5-5 Device Specifications are Used to Identify the Desired Device for a Given 
Operation 
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As was previously discussed, you can assign logical names to specific devices on the 
system. Using these logical names, you can access files from other devices. If you 
specify a file using a logical device name, you can access the file regardless of which 
physical device holds the disk or tape containing your file. Your system manager will 
ensure that the logical device names are always equated to the correct physical devices. 
The device name should precede the directory name and be terminated with a colon (:). 

For example: 

$ DIRECTORY DRAO : [SMITH] 

gives you a listing of the files in the [SMITFfJ directory on the device DRAO:. You can 
also move files from one device to another using the COPY command. See Table 5-15 
for some examples of using other devices. 
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Table 5-15 Examples of Using Other Devices 



Operation 



Comments and Examples 



Listing files in 
a directory on 
another disk 



Locating a file 
in a directory on 
another disk 



Copying a file from 
another disk to 
your default disk 
and directory 

Listing all files on 
a tape device 

Finding a file on a 
tape device 



Copying a file from 
tape to a disk 



Lists all files in the directory [SMITH] located on the disk 
DBA2: 

$ DIRECTORY DBA2 : [SMITH] 

Searches for the file name MYFILE.TXT in the directory 
[SMITH] located on the disk DBA2: 

$ DIRECTORY DBA2 : [ SMITH] MYFILE .TXT 

Copies the latest version of MYFILE.TXT from another disk to 
your default disk and directory 

$ COPY DBA2: [ SMITH] MYFILE . TXT MYFILE.TXT 

Lists all files on a magnetic tape on device MTA2: 

$ DIRECTORY MTA2 : 

Searches for the file MYFILE.TXT on a magnetic tape on device 
MTA2: 

$ DIRECTORY MTA2 : MYFILE. TXT 

Copies the file MYFILE.TXT from the tape on MTA2: to your 
default disk and directory 



$ COPY MTA2 : MYFILE . TXT * . * ; * 
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You can also move directories from one device to another. Table 5—16 shows you how 
to move a hierarchical file structure from device DBAO: to device DRA2:. 



Table 5-16 Moving a Hierarchical File Structure from one Disk Device to 
Another 



Command Comments and Examples 



COPY Copies all versions of the files in and below the SFD [SMITH.UTLCOM] 

on device DBAO: to the directory [JONES] on device DRA2:, preserving 
the hierarchical file structure. 



$ COPY DBAO : [SMITH.UTLCOM. ..]*.*.* DRA2 : [JONES ...]*.*.* 

Copies all versions of the files in and below the SFD [SMITH.UTLCOM] 
on device DBAO: to the directory [JONES .UTLCOM] on device DRA2:, 
preserving the hierarchical file structure. If the file UTLCOM.DIR does 
not exist in the directory [JONES], the COPY command fails. 

S COPY DBAO: [SMITH.UTLCOM. ..]*.*;* DRA2 : [JONES .UTLCOM. ..]*.*;* 
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5.16 PROTECTING DISK AND TAPES 
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Figure 5-6 File Access to Disk and Tape Volumes 
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5.17 SUMMARY 



Directory Type 


Example 


Naming Convention 


Master File 
Directory (MFD) 


[000000] 


Each disk contains one MFD, named 
[000000]. 


User File 
Directory (UFD) 


[SMITH] 


Your user name is usually your UFD 
name. 


Subdirectory (SFD) 


[SMITH.PAYROLL] 


You choose the names for the 
subdirectories you create. 



Use the DIRECTORY command to: 

Find files on a peripheral storage device on your system 
Display the contents of directories or the characteristics of files 

You may want to change file protection to: 

Restrict access to your files 

• Prevent unauthorized moving or deletion of files 

Assign a special protection code for all files created in a particular directory 

• Delete a subdirectory 

There are two means of protecting files: 

User Identification Code (UlC-based) protection 

• Access Control Lists (ACLs) 
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5.18 APPENDIX A—DEVICE INFORMATION 



Table 5-17 Codes for Some Supported Devices on a VMS System 



Code Device Type 



CS Console Storage Device 

DB RP05, RP06 Disk 

DD TU58 Cassette Tape 

DJ RA60 Removable Disk 

DL RL02 Cartridge Disk 

DM RK06, RK07 Cartridge Disk 

DQ R80 Disk 

DR RM03, RM05, RM80, RP07 Disk 

DU RA82, RA80, RA81, RC25, RD54, RD53 Disk, RX33, RX50 Floppy 
Diskette 

DX RX01 Floppy Diskette 

DY RX02 Floppy Diskette 

LA LPA11-K Laboratory Peripheral Accelerator 

LC Line Printer on DMF32 

LP Line Printer on LP11 

LT Interactive Terminal or Terminal Server 

MB Mailbox 

MF TU78 Magnetic Tape 

MS TS 1 1 , TU80 Magnetic Tape 

MT TE16, TU45, TU77 Magnetic Tape 

MU TA78, TK50, TU81 Magnetic Tape 
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Table 5-17 (Cont.) Codes for Some Supported Devices on a VMS System 



Code Device Type 



NET Network Communication Logical Device 

NL System "Null" Device 

OP Operator's Console 

RT Remote Terminal 

TT Interactive Terminal on DZ11 

TX Interactive Terminal on DMF32 

XA DR11-W General Purpose DMA Interface 

XD DMP-11 Synchronous Communications Lines 

XE DEUNA Communication Device 

XF DR32 Interface Adapter 

XG DMF32 Synchronous Communications Lines 

XJ DUP11 Synchronous Communications Lines 

XM DMC11 Synchronous Communications Lines 

XQ DEQNA Communication Device 
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DCL allows you to omit the controller character and the unit number in device 
specifications. The effect of leaving out these parts depends on the command you use. 
Most DCL commands interpret an incomplete device specification as a physical device 
specification, or one that is meant to signify a single physical device. Other commands 
interpret an incomplete device specification as a generic device specification, or one that 
specifies a group of devices on your system. 

The commands that interpret an incomplete device specification as a physical device 
name include: INITIALIZE, DISMOUNT, DEALLOCATE and all file manipulation 
commands. Physical device specifications always default missing controller characters 
to A, and missing unit numbers to 0. For example, the system interprets the incomplete 
device specification DB: as DBAO:. 

One command that interprets an incomplete device specification as a generic device name 
is SHOW DEVICE. Table 5-18 summarizes device terminology, while Table 5-19 
demonstrates the syntax you use when specifying devices. For additional information 
concerning commands, refer to the VMS DCL Dictionary. 
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Table 5-18 Summary of Device Terminology 



Term 



Peripheral Device 



Mass Storage Device 



Record-Oriented Device 



Physical Device Name 



Logical Device Name 



Generic Device Name 



Cluster Device Name 



Definition 



A unit on the system used for information input, 
output, or storage. A device can be classified either 
as a mass storage device or as a record-oriented 
device. 

A device used for storing information on a magnetic 
medium. Examples include disks and tapes. 

A device used for reading and writing single units 
of data. Terminals, printers, and card readers are 
examples of these devices. 

A specific physical device on the system. Consists 
of a device-type code, a controller character, and a 
unit number. 

A synonym for a physical device name. Often used 
to refer to a specific volume, regardless of the device 
on which it is mounted. Usually the system manager 
sets up logical names. 

A group of devices, consisting of a physical device 
name that does not specify the controller and the 
unit number. 

Name of a device on a node in a cluster, consisting 
of a cluster node name or allocation class and a 
device name separated by a dollar sign. 
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Table 5-19 Generic Specification with the SHOW uEVICE Command 



Operation 



Comments and Examples 



Using Physical Device Names 

Specifying a particular device 

Using Generic Device Names 

Specifying all devices of a given type 
except terminals 



Specifying all devices of a given type 
on a single controller 



Specifying all devices of a given 
type at the same position on different 
controllers 



Specifying all te rmin als 



Specifying your assigned terminal 



Displays full information on the magnetic 
tape (MT) unit (0) on controller A 

$ SHOW DEVICE /FULL MTAO : 



Displays brief characteristics of all RA60 
devices (DJ) 

$ SHOW DEVICE DJ: 

Shows brief characteristics of all MT 
magnetic tape devices on controller A 

$ SHOW DEVICE MTA: 

Displays brief characteristics of all terminals 
(TT) with unit number 1 on any controller 

$ SHOW DEVICES TT1 : 

Displays brief characteristics of all system 
terminals 

$ SHOW DEVICE T: 

Displays brief characteristics of your 
assigned terminal (TT: is a system-defined 
logical name equating to your terminal) 

$ SHOW DEVICE TT : 
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5.19 APPENDIX J5 — NETWORKING INFORMA^x^N 

5.19.1 Managing Files on Another VMS System in Your Network 

5.19.1.1 Methods of File Management in a Network 

VMS systems allow you to manage files on devices connected to other systems without 
compromising the VMS file security features. You have several choices for managing 
files located on devices connected to another system. These choices include: 

Using the SET HOST command - 

You can use the SET HOST command to connect your terminal (through the 
current host processor) to another processor, called the remote processor, and enter 
DCL file-manipulation commands. This requires that both processors run DECnet 
and that you know a user name and password of an account on the remote system. 
The account you use on the remote system supplies values to the remote system 
to process your DCL file-manipulation commands. 

Using an access-control string in your DCL commands - 

You can include an access^ontrol string in the DCL file-manipulation commands 
that function across the network. (This section addresses access-control strings.) 
The access-control string includes both the user name and password of an account 
on a remote system. The account referenced by the access-control string also 
provides default values to the remote system to process your DCL file-manipulation 
commands. 

Using a proxy account - 

You can use the defaults supplied by a proxy account when you use DCL 
file-manipulation commands that function across the network. (A proxy account, 
if the system manager establishes one for you, associates your user name with an 
account on the remote system.) The account on the remote system associated with 
your user name provides the default values the remote system needs to process 
your DCL file-manipulation commands. 

Using the DECnet defaults - 

The system manager can establish a default DECnet account. If this account is 
created, it will supply default values to DCL file-manipulation commands entered 
across the network. 
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5.19.2 Using DCL File-Manipulation Commands in a Non-VAXcluster 
Network Environment 

5.19.2.1 Two Node Specification Formats 

This section first discusses using DCL file-manipulation commands in a network that 
does not contain a VAXcluster system. Then it looks at factors concerning managing 
files on a VAXcluster system. s 

When you manage files on a device connected to a remote node, it is necessary to 
include the node specification of the remote processor in the file specification of DCL 
file-manipulation commands. Two formats for the node specification follow. 

1. Nodename:: 

2. Nodename "access control string":: 

When you use the Nodename:: format, the remote system takes the following action: 

• It processes your file-manipulation request as though your request was issued 
from its default DECnet account. If there is no default DECnet account your 
file-manipulation request fails. 

• It uses the UIC of its default DECnet account to determine the file access rights. 

• It obtains default values from its default DECnet account for fields you omit from 
file specifications in your file-manipulation request. 

When you include an access-control string, the remote system takes a different action 
me access-control string you provide consists of a user name and password in the 
format user-name password. When you use this format, the remote system takes the 
following action: 

It processes your file-manipulation request under a process created from the 
account specified in the access-control string. 

• It uses the UIC of the account specified in the access-control string to determine 
file access rights. 

• It obtains default values from the account specified in the access-control string for 
fields you omit from file specifications in your file-manipulation request. 

Table 5-20 shows examples of specifying files on a device connected to a remote node. 
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Tabie 5-20 Examples of Specifying Files on Remote Nodes 



Examples Comments 

$ DIRECTORY DIPPER: :DBA1: [SMITH] PAY. FOR; 1 



Specifies the file PAY.FOR;l in the directory 
[SMITH] on disk DBA1: on remote node DIPPER:. 



$ DIRECTORY DIPPER"BILL SMITH" : :DBA1 : [SMITH] PAY. FOR; 1 



Specifies the same as the preceding example. Access 
to the file uses the UIC of user SMITH. 



$ DIRECTORY DIPPER"BILL SMITH" :: PAY. FOR; 1 



Specifies the same as the preceding example. The 
process supplies the defaults under the account for 
SMITH. 



$ DIRECTORY DIPPER"BILL SMITH":: [SMITH.DOCJPAY.DAT 



Specifies the file PAY.DAT in the subdirectory 
[SMTTH.DOC] on the default disk of user SMITH 
on node DIPPER:. 



The file management commands that work across a network are a subset of the 
commands used to manage files on an individual VAX processor. Table 5-21 illustrates 
how to use DECnet-VAX file management commands. 
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Table 5-21 DECnet-VAX DCL File-Manipulation Command Summary 



Function 



Adding the contents of 
one or more files to the 
end of another file (files 
may be local or remote) 



Copying one or more files 
to or from a remote node 



Creating a disk file on a 
remote node 



Comments and Examples 



Appends the contents of file DEMO.DAT in the directory 
[JAFFE] on the remote node BOSTON:: to the file 
TEST.DAT in your current directory on your local node. 

$ APPEND BOSTON" JAFFE ANN" : : DEMO. DAT TEST.DAT 

Copies the file DEC12.DAT from your current directory 
to the directory [JANES] on the remote node WHYNOT::. 
Defaults on the remote node come from the UAF record 
specified within quotes. The same file name is retained. 

$ COPY DEC12.DAT WHYNOT" JANES JIL" : :*.* 

Creates the file TEST.DAT in the directory [MODEL] on 
diskDBAl: of remote node TRNTO::. 



Displaying information 
about a file 



$ CREATE TRNTO: :DBA1: [MODELJTEST.DAT 
Text is entered into file TEST.DAT 
CTRL/ 2 

Lists the files in the subdirectory [JANES.SUB1] located 
on the remote node WHYNOT::. 



$ DIRECTORY WHYNOT"JANES JIL": : [JANES. SOB1] 
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Table 5-21 (Cont.) DECnet-VAX DCL File-Manipulation Command Summary 



Function Comments and Examples 



Displaying the contents of Displays the file PAY.DOC;l in the directory [GREEN] 
a file at a terminal on a on disk DBA1: located on remote node DIPPER::, 
remote node 

$ TYPE DIPPER: :DBA1: [ GREEN] PAY. DOC; 1 

Deleting one or more files Deletes all versions of the file PAY.FOR in subdirectory 
at a remote terminal [JONES.SUB1] located on remote node WHYNOT::. 

$ DELETE WHYNOT"JANES JIL" : : [ JANES -SUB1] PAY.FOR; * 
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5.19.3 Using DCL File-Manipulation Commands in a VAXcluster 
Environment 

5.19.3.1 Two Cluster Device Specification Formats 

You can also manipulate files on a device connected to a system that is in a cluster. To 
do this, include a cluster device specification in your DCL file-manipulation commands. 
A cluster device specification has one of the following formats: 

1. node-name$device-name 

2. $allocation-class$device-name 

The first format shows a cluster device specification consisting of the name of the 
device, preceded by the name of the node, followed by a dollar sign ($). 

A sample cluster device specification of this type follows: 

PETER$DUA1 : 

In the example above, PETER is the name of the node, DUA1 is the name of the 
physical device, and the dollar sign ($) is a delimiter. 

The second format shows the device name of the cluster device specification prefixed 
by a number. The prefix number is called an allocation class, and is a number between 
1 and 255. 

A sample cluster device specification of this type follows: 

S1$DUA0: 

Only devices set up in a special way can use an allocation class as part of their 
device specifications. The system manager is responsible for setting up the devices and 
choosing an allocation class for each node in the cluster. 

You may want to check the names of nodes and devices while you are manipulating 
your files. To do this, DCL provides the following commands: SHOW NET SHOW 
CLUSTER, and SHOW DEVICES. Table 5-22 fists commands you can use to 
obtain information about nodes and devices in your systems environment. For more 
information on VAXclusters systems, refer to the VMS VAXcluster Manual. 
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Table 5-22 Commands Used to Determine the Nodes and Devices in Your 
Systems Environment 



Operation 



Command/Example Comments 



Determine the $ show net 

names of nodes in 
a network 

Determine the $ show cluster 

names of nodes in 
a cluster 



Determine the 
names of devices 
accessible to your 
node 



$ SHOW DEVICES 



Displays a list of nodes in your network. 



Displays a list of nodes (HSC and VAX) 
in your cluster. 



Displays a list of devices accessible to 
your node. 
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5.20 WRITTEN EXERCISE I 

Suppose your default directory contains the following files: 

A.DAT/l A. FOR; 2 AREA.FOR;2 AREA.FOR;l 

B.DAT;3 B.FOR;l C.DAT;4 C.FOR;l 

MAILD22.DAT; 2 MAILF22.DAT;2 MAILIST.COB; 1 MAILJ14 -DAT; 1 

1. List the files that are specified by the following file specifications (using the 
DIRECTORY command): 

a. *K)R;2 

b. *-FOR 

c. A*.*;* 

d. A%%%.*;* 

e. %X>AT 

f. *.*;* 

2. Give a single file specification that describes the following lists of files: 

a. A£>AT;1, AK)R;2 

b. AJDAT;1, BX>AT;3, C.DAT;4 

c. MAILD22.DAT;2, MAILF22X»AT;2, MAHJ14X>AT;1 

d. ADAT;1, MAEJ14X>AT;1 
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5.21 WRITTEN EXERCISE E 

Next to each file maintenance operation, write the letter that corresponds to the VMS 
command best suited to accomplish it. Specify each command at least once. 

Commands 

a. APPEND 

b. COPY 

c. DELETE 

d. DELETE/CONFIRM 

e. DIFFERENCES 

f. DIRECTORY 

g. DIRECTORY/OUTPUT=file-specification 
h. PRINT 

i. PURGE 
j. RENAME 
k. TYPE 

Operations 

!• Display the contents of a file at your terminal. 

2 - Display the contents of your default directory at your terminal. 

3- Remove a specified file from your default directory. 

4 - Remove all but the most recent version of a specified file from your 

default directory. 

5- Create an exact duplicate of a file in your default directory. 

6 - List the contents of a file at the default system printer. 

7 - Compare the contents of two files. 

8- Add the contents of one file to another. 

9- Change a directory name to a new directory name. 

10. 



Display the name of each file in your default directory and remove 

or retain it by entering a "Y" or an "N" at your terminal. 

11 • Li st the contents of your default directory in a file for future reference. 
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5.LL WKil IJCIX CAJ2,JK^10JD ±11 

Next to each directory maintenance operation, write the letter of the VMS command 
best suited to perform the job. You may use some commands more than once; you will 
not use others at all. 

Commands 

a. COPY 

b. CREATE 

c. CREATE/DIRECTORY 

d. DELETE 

e. DELETE/DIRECTORY 

f. DIRECTORY 

g. RENAME 

h. SET DEFAULT 

i. SET PROTECTION 

j. SHOW DEFAULT 

k. SHOW PROTECTION 

Operations 

1. Display the name of your current default directory. 

2. Display the contents of a directory hierarchy. 

3. Remove a directory from a directory hierarchy. 

4. Add a directory to a directory hierarchy. 

5. Move files from one directory to another. 

6. Change your current default directory. 

7. Change the protection code of a directory file. 

8. Display the name of your current default device. 

9. Change your current default device. 
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5.23 WRITTEN EXERCISE IV 

Each of the following questions describes an operation a user wants to perform on a 
given disk or tape file. Given the UIC of the user, and the owner UIC and protection 
code of the file, its directory, or its volume, determine whether the file system will 
permit the operation to occur. If the operation is permissible, write the word TRUE in 
the space that precedes the question; if it is not, write the word FALSE. 



A user with a UIC of [100,200] wants to delete a file on a tape volume. 



Volume Owner UIC : 
Volume Protection Code: 



[100,200] 
(S:RWED,0:RWED,G:RWED,W:RE) 



A user with a UIC of [363,2] wants to create a file on an RX33 disk 
volume. 



Volume Owner DIC: 
Volume Protection Code: 



[363,0] 
(S:RE,0:RWED,G:RE,W) 



A user with a UIC of [4,4] wants to read a file on an RA60 disk volume. 



File Owner UIC: 

File Protection Code: 



[411,22] 
(S,0:RWED,G,W:R) 



A user with a UIC of [100,200] wants to update a record in a file on an 
RA80 disk volume. 



Volume Owner UIC: [1,1] 

Volume Protection Code: (S :RWED, 0;RWED, G:RWED, W:RWED) 

Directory Owner UIC: [100,210] 

Directory Protection Code: (S:RWE,0:RWE, G:RWE, W:RE) 

File Owner UIC: [100,210] 

File Protection Code: (S :RE, 0:RWED, G:RWE, W:RE) 



A user with a UIC of [521,6] wants to read a file on an RA81 disk volume. 



Volume Owner UIC: [1,1] 

Volume Protection Code: (S:RWED, 0:RWED, G:RWED, W:RWED) 

Directory Owner UIC: [521,13] 

Directory Protection Code: (S:RWE,0:RWE, G, W) 

File Owner UIC: [521,13] 

File Protection Code: (S:R, 0:RWED, G:R, W:R) 
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1. Create a subdirectory called [.SUB1]. 

2. Copy some files from your login directory into [.SUB1]. 

3. Move yourself to that subdirectory. 

4. Obtain a directory listing of all files in the subdirectory. 

5. Combine two files to create a new file named NEWFILE.DAT. 

6. Create another subdirectory beneath [.SUB1] and name the new subdirectory 

[.SUB2]. 

7. Copy some files from [.SUB1] into [.SUB2]. 

8. Obtain a directory fisting of all files in the subdirectory. 

9. Delete both subdirectories. 
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5.25 LABORATORY EXERCISE H 



1. Create a file in your login directory. What protection code does this newly created 
file have and how did it get that protection code? 

2. Change the protection code for this file to (S:R,0:R,G;R,W:R). Display the 
protection code to verify the change. 

3. Delete this file. What happened and why? 

4. Change your DEFAULT protection code to (S:R,0:RWED,G:R,W:R). Create a 
new file named NEWFILE.TXT. What protection code does this new file have and 
why? 

5. Change your DEFAULT protection to give all persons in your UIC group RWED 
access and all persons in the WORLD category RWE access. 
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5.26 LABORATORY EXERCISE HI 

1. Choose a file in your directory. Issue a DCL command to obtain Access Control 
List information regarding that file. 

2. Modify the UIC protection on the above file so that your group has no access. 

3. Modify the ACL information to allow Read, Write, and Execute access to the file. 

4. Check to see if an ACL was created. Have some of your fellow students try to 
access the file. 

5. Delete the ACL on the above file. 
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5.27 WRITTEN EXERCISE I— SOLUTIONS 



1. List the files that are specified by the following file specifications: 

a. *.FOR;2 

A. FOR; 2, AREA. FOR; 2 

b. *JOR 

A.FOR;2, AREA.FOR;2, AREA. FOR; 1, B.FOR;l, C.F0R;1 

C. A*.*;* 

A.DAT;1, A.FOR;2, AREA.FOR;2, AREA.FOR;l 

d. A%%%.*;* 

AREA. FOR; 2, AREA. FOR; 1 

e. %X>AT 

A.DAT;1, B.DAT;3, C.DAT;4 

f. *.*;* 

All files 

2. Give a single file specification that describes the following lists of files: 

a. ADAT;1, AJOR;2 

A. * or A. *;* 

b. AX>AT;1, BX)AT;3, C.DAT;4 

%.DAT or %.DAT;* 

c. MAILD22.DAT;2, MAELF22.DAT;2, MAELJ14JDAT;1 

MAIL*. DAT;* or MAIL%%%.DAT 

d. A.DAT;1, MAILJ14DAT;1 

*.DAT;1 
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5.28 WRITTEN EXERCISE H— SOLUTIONS 
Commands 

a. APPEND 

b. COPY 

c. DELETE 

d. DELETE/CONFIRM 

e. DIFFERENCES 

f. DIRECTORY 

g. DIRECTORY/OUTPUT=file-specificatioii 
h. PRINT 

i. PURGE 
j. RENAME 
k. TYPE 

Operations 

1. k Display the contents of a file at your terminal. 

Display the contents of your default directory at your terminal. 

Remove a specified file from your default directory. 

Remove all but the most recent version of a specified file from your 
default directory. 

Create an exact duplicate of a file in your default directory. 

List the contents of a file at the default system printer. 

Compare the contents of two files. 

Add the contents of one file to another. 

Change a directory name to a new directory name. 

Display the name of each file in your default directory and remove 
or retain it by entering a "Y" or an "N" at your terminal. 

List the contents of your default directory in a file for future reference. 



2. 


f 


3. 


c 


4. 


i 


5. 


b 


6. 


h 


7. 


e 


8. 


a 


9. 
10. 


j 
d 


11. 


8 
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5,29 WRITTEN EXERCISE HI— SOLUTIONS 
Commands 

a. COPY 

b. CREATE 

c. CREATE/DIRECTORY 

d. DELETE 

e. DELETE/DIRECTORY 

f. DIRECTORY 

g. RENAME 

h. SET DEFAULT 

i. SET PROTECTION 

j. SHOW DEFAULT 

k. SHOW PROTECTION 

Operations 

1. j Display the name of your current default directory. 

Display the contents of a directory hierarchy. 
Remove a directory from a directory hierarchy. 
Add a directory to a directory hierarchy. 
Move files from one directory to another. 
Change your current default directory. 
Change the protection code of a directory file. 
Display the name of your current default device. 
Change your current default device. 



2. 


f 


3. 


d 


4. 


c 


5. 


s 


6. 


h 


7. 


i 


8. 
9. 


j 
h 
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5.30 WRITTEN EXERCISE IV— SOLUTIONS 



1. FALSE A user with a UIC of [100,200] wants to delete a file on a tape volume. 

Volume Owner UIC: [100,200] 

Volume Protection Code: (S :RWED, 0:RWED, G:RWED, W:RE) 

Files on a tape volume cannot be deleted. 

2. TRUE A user with a UIC of [363,2] wants to create a file on an RX33 disk 

volume. 

Volume Owner UIC: [363,0] 

Volume Protection Code: (S:RE, 0:RWED, G:RE, W) 

The user is a member of the same group as the owner of the volume. Since group 
members have been granted EXECUTE rights, the user can create a new file. 

3. TRUE A user with a UIC of [4,4] wants to read a file on an RA60 disk volume. 

File Owner UIC: [411,22] 

File Protection Code: (S, 0:RWED, G, W:R) 

The user belongs to the SYSTEM user category. System users do not have READ 
access rights to the file. However, READ access rights have been granted to 
members of the WORLD category; therefore, the user will be able to read the file. 
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RA80 disk volume. 



Volume Owner UIC : 
Volume Protection Code: 
Directory Owner UIC: 
Directory Protection Code: 
File Owner UIC: 
File Protection Code: 



[1,1] 

(S:RWED,0;RWED,G:RWED,W:RWED) 

[100,210] 

(S:RWE,0:RWE,G:RWE,W:RE) 

[100,210] 

(S:RE,0:RWED,G:RWE,W:RE) 



The user can access files on the volume because all access rights to the volume 
have been granted to all user categories. The user is a member of the same group 
as the owner of the file and the directory in which it is listed. Members of the 
GROUP category have been granted WRITE access rights; therefore, the user can 
update the file. 

5. FALSE A user with a UIC of [521,6] wants to read a file on an RA81 disk 
volume. 



Volume Owner UIC: 
Volume Protection Code: 
Directory Owner UIC: 
Directory Protection Code: 
File Owner UIC: 
File Protection Code: 



[1,1] 

(S:RWED,0:RWED,G:RWED,W:RWED) 

[521,13] 

(S:RWE,0:RWE, G,W) 

[521,13] 

(S:R,0:RWED,G:R,W:R) 



The user can access files on the volume because all access rights to the volume 
have been granted to all user categories. The user is a member of the same group 
as the owner of the file and the directory in which it is listed. Members of the 
GROUP category, however, cannot read the directory; therefore, the user will be 
unable to read tbe file. 
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5.3 1 LABORATORY EXERCISE I— SOLUTIONS 

1. Create a subdirectory called [.SUB1]. 

$ CREATE/DIRECTORY [.SUB1] 

2. Copy some files from your login directory into [.SUB1]. 

$ COPY/LOG EXISTING-FILE-NAMES [XXX.SUB1]* 

3. Move yourself to that subdirectory. 

$ SET DEFAULT [XXX.SUB1] 

4. Obtain a directory listing of all files in the subdirectory. 

$ DIRECTORY 

5. Combine two files to create a new file named NEWFILE.DAT. 

$ COPY FILE1,FILE2 NEWFILE.DAT 

6. Create another subdirectory beneath [.SUB1] and name the new subdirectory 
[.SUB2]. 

$ CREATE/DIRECTORY [XXX. SOB1 . SUB2] 

or 

$ CREATE/DIRECTORY [.SUB2] (Assuming you are in the subdirectory [.SOB1]) 

7. Copy some files from [.SUB1] into [.SUB2]. 

S COPY EXISTING-FILE-NAMES [.SUB2]* 

8. Obtain a directory fisting of all files in the subdirectory [.SUB2]. 

S DIRECTORY [.SUB2] 

9. Delete both subdirectories. 

$ DELETE *.*;* (Assuming you are in subdirectory [.SUB2] 

$ SET DEFAULT [-.SUB1] 

$ SET PROTECT ION=(0:RWED) SDB2.DIR 

$ DELETE *.*;* 

$ SET DEF [-] (Login directory) 

$ SET PROTECT ION=(0:RWED) SUB1.DIR 

$ DELETE SUB1.DIR;! 
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5.32 LABORATORY EXERCISE H— SOLUTIONS 

1. Create a file in your login directory. What protection code does this newly created 
file have and how did it get that protection code? 

$ CREATE MYFILE.TXT 
Type in text 
CTRL/Z 

The protection applied to this file is the system default protection the VMS system 
puts on newly created files. 

2. Change the protection code for this file to (S:R,0:R,G;R,W:R). Display the 
protection code to verify the change. 

$ SET PROTECTI0N=(S:R,O:R,G:R,W:R) MYFILE.TXT 
$ DIRECTORY/PROTECTION MYFILE.TXT 

3. Delete this file. What happened and why? 

$ DELETE MYFILE.TXT;* 

The system issues a system message informing you that you cannot delete (his file, 
because you changed the file protection so that the owner does not have DELETE 
privilege. 

4. Change your DEFAULT protection code to (S:R,0:RWED,G:R,W:R). 

$ SET PR0TECTI0N=(S:R,O:RWED,G:R,W:R) /DEFAULT 

Create a new file named NEWFILE.TXT. What protection code does this new file 
have and why? 

$ CREATE NEWFILE.TXT 

Type in text 

CTRL/Z 

$ DIRECTORY/PROTECTION NEWFILE.TXT 

By changing your DEFAULT protection, you specify that all files now created will 
have this new default protection. 

5. Change your DEFAULT protection to give all persons in your UIC group RWED 
access and all persons in the WORLD category RWE access. 

$ SET PROTECTION=(G:RWED,W:RWE)/DEFAULT 
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5.33 LABORATORY EXERCISE EI— SOLUTIONS 

1. Choose a file in your directory. Issue a DCL command to obtain Access Control 
List information regarding that file. 

S DIRECTORY/SECURITY file-name 

2. Modify the UIC protection on the above file so that your group has no access. 

$ SET PROTECTION (G) file-name 

3. Modify the ACL information to allow Read, Write, and Execute access to the file. 

$ EDIT/ACL file-name 

( IDENTIFIER=xxxx, ACCESS=READ+WRITE+EXECOTE ) 

4. Check to see if an ACL was created. Have some of your fellow students try to 
access the file. 

$ DIRECTORY/SECURITY file-name 

5. Delete the ACL on the above file. 

S SET ACL/DELETE file-name 
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6.1 INTRODUCTION 

Previously, you learned to enter instructions to the operating system and to specify the 
locations of devices, directories, and files. The command strings and device and file 
specifications that perform these operations are sometimes lengthy. This complexity is 
an invitation to typographical and grammatical errors. 

This module introduces logical names and demonstrates how to to use them in place of 
complicated device and file specifications in command strings. It also explains how to 
create and use symbols to tailor the command language. 

Finally it describes how to define terminal keys to perform frequently used functions. 

6.2 OBJECTIVES 

• To make file references device-independent, you should be able to: 

— Use the logical names the VMS system defines for all users 

— Create and use logical names for file access 

To customize the command language for particular needs, you should be able to: 

— Create and use symbols as command synonyms 

— Use symbols as variables in DCL expressions 

— Use symbols as an integral part of command procedures 

Finally, you should be able to define and use terminal keys to speed up execution 
of frequently used DCL commands. 

6.3 RESOURCES 

VMS DCL Dictionary 
VMS DCL Concepts Manual 
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6.4 LOGICAL NAME ASSIGNMENTS 

A logical name is a name you can use in place of all or part of a file specification. 
When you issue DCL commands, you can use logical names in place of the device 
name or file specification equated to the logical name. The system translates the logical 
name to the corresponding equivalence string(s). 

Equivalence strings are usually the name of a device, some portion of a file specification, 
or another logical name. 

Logical names are also used to pass data among programs, or between a command 
procedure and a program. 

To create logical name assignments, use either the ASSIGN or DEFINE command. 
The format is: 

$ DEFINE logical-name equivalence stringt,...] 

$ ASSIGN equivalence-name [,...] logical-name 

Logical names and their equivalence strings can each have a maximum of 255 characters, 
including alphanumeric characters, the dollar sign (?), and the underscore (J. Any 
other characters must be enclosed in quotation marks. 
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6.4.1 Logical Name Tables 

Logical names and their equivalence strings are stored in logical name tables. During a 
terminal session, your process has at least four logical name tables associated with it 

Process Logical Name Table (LNM$PROCESS_TABLE) 

The contents of your process logical name table is known only to your current 
process. It contains process-private logical name assignments. 

Job-Wide Logical Name Table (LNM$JOB_YYYYYYYY, where YYYYYYYY is 
the number the system assigns to your job) 

The contents of your job-wide logical name table is known to your process tree, 
which is your login process and all of its subprocesses. It contains shareable 
logical name assignments. 

Group Logical Name Table (LNM$GROUP_000XXX, where XXX represents your 
UIC group number) 

The contents of the group logical name table is known to all users whose UIC 
group number matches your own. This also contains shareable logical name 
assignments. Privilege is needed to add logical names to this table. 

System Logical Name Table (LNM$SYSTEM_TABLE) 

The contents of the system logical name table is known to all processes on your 
system. This also contains shareable logical name assignments. Privilege is needed 
to add logical names to this table. 

The logical names catalogued in your process logical name table are referred to as 
process-private logical names, while the logical names catalogued in the job-wide, 
group, and system logical name tables are known as shareable logical names. 

Figure 6-1 illustrates the relationship between your terminal, the operating system, and 
the logical name tables associated with your process. 



CUSTOMIZING THE USER ENVIRONMENT 



6-7 



S logical-name command 
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Figure 6-1 The Relationship Between Your Terminal, the Operating System, and the Logical 
Name Tables Associated with Your Processor 



6-8 CUSTOMIZING THE USER ENVIRONMENT 



6.4.2 Common User Operations Dealing with Logical Names 

As a user you may want to: 

Display the contents of logical name tables 
Determine the equivalence name of a logical name 

Add or override logical name assignments in your process logical name table 
Remove a logical name from your process logical name table 
The following sections describe each of the above steps in detail. 
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6,4.2.1 Adding Logical Names 

To add logical names, you can use either the ASSIGN or the DEFINE command. The 
ASSIGN command syntax is: 

$ ASSIGN[/table-name] [/mode-name] 
Device: equivalence-name[,..J 
Log name: logical-name[:] 

Example: 

$ ASSIGN DRAO: [SMITH. UANDC] MINE 

The DEFINE command syntax is: 

$ DEFINE[/table-name][/mode-name] 
Log name: logical-name[:] 
Equ name: equivalence-name[,...] 

Example: 

$ DEFINE MINE DRAO: [SMITH.OANDC] 

Both examples above assign the logical name MINE to the disk DRAO, the directory 
name [SMITH], and the subdirectory name [.UANDC], 

$ CREATE/DIRECTORY/LOG [SMITH.LOG] 
%CREATE-I-CREATED, DISK: [SMITH.LOG] created 

$ ASSIGN [SMITH.LOG] MY_LOG 

$ COPY/LOG [SMITH] MYFILE.TXT MY_LOG 

%COPY-S-COPIED, DISK: [ SMITH] MYFILE. TXT ;1 copied to 
DISK: [SMITH.LOGJMYFILE.TXT; 1 (1 block) 

$ TYPE MY LOG: MYFILE. TXT 

This is a~file for use in displaying the use of logical names 

to abbreviate devices and file specifications. This is m 

the module entitled "Customizing the User Environment . 

$ 

Example 6-1 Using Logical Names to Abbreviate Device and File Specifications 
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6.5 USING LOGICAL NAMES 
6.5.1 Logical Name Translation 

When the system encounters a file specification or device name in a command string it 
performs logical name translation on it automatically. The following steps are performed 
by the system to translate logical names that have single equivalence strings. 

If any of the following conditions exist, logical name translation terminates: 

— Ten translations have already been made (recursively). 

— The left-most component of the specification is not delimited by a colon, a 
space, a comma, or an end of line. 

— The equivalence string is a logical name that has the Terminal attribute. If a 
logical name as the Terminal attribute, the translation is completed after the 
first translation. 

— If the logical name has the Concealed attribute, the translation normally 
displays the logical name for the device, rather than the physical name for 
the device. 

• The system searches the Process, Job, Group, and System logical name tables in 
that order for the first logical name match. A logical name match occurs when: 

— The part of the specification preceding the first delimiter matches an entry in 
a logical name table. 

— The entire specification matches an entry in a logical name table. 

If a match occurs, the equivalence name replaces the logical name and step 1 is 
repeated. Otherwise, logical name translation terminates. 

Both Terminal and Concealed are translation attributes. They are defined by using 
the /TRANSLATION_ATTRIBUTES= qualifier for either the DEFINE or ASSIGN 
commands. Refer to the VMS DCL Dictionary for further details. 
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6.6 RECURSIVE TRANSLATION 

This section describes the steps that occur when the system does a recursive translation: 
The following command is entered: 

$ DIRECTORY SYS$LOGIN 

The file specification passed to the DIRECTORY command consists of a single 
component SYS$LOGIN. The symbol contains no delimiters. When the system searches 
your logical name tables, it locates the following definition, which is m the format used 
by the SHOW LOGICAL command: 

"SYS$LOGIN" = "DISKJOSER: [SMITH]" (LNM$JOB_8016D000) 

Given this assignment, the system substitutes the equivalence string, DISK_ 
USER-[SMITH], for the original specification SYS$LOGIN. Next, the system 
searches your logical name tables in an attempt to translate DISKJUSER, the left-most 
portion of the revised specification. This search locates the physical device name 
DBAO- with the Terminal attribute and the Concealed attribute, as the equivalence string 
assigned to the logical name DISKUSER. The SHOW LOGICAL command displays 
this relationship as follows: 

"DISK_USER" = "DBAO:" (LNM$SYSTEM_TABLE) 

The system now substitutes the equivalence string DBAO: for the logical name 
DISK.USER to produce the file specification DBAO: [SMITH]. 

Since the logical name DISK.USER has the Terminal attribute assigned, further iterative 
translation is prevented. And, since the Concealed attribute is assigned, you are assured 
that DBAO- is the physical device name. In this case, the DIRECTORY image looks 
for files cataloged in DBAO: [SMITH] but uses DISK_USER: [SMITH] in the heading of 
its display. Concealed device names are useful when, as in this case, the logical name 
has more meaning to the user than the physical device name. 

To complete the processing of the file specification, the system substitutes default values 
for fields that remain unspecified. In this example, no file name, file type, or version 
number has been specified. Since you have entered the DIRECTORY command, the 
system substitutes wildcard characters (*) in the remaining fields of the specification. It 
does this on the assumption that you want to list the contents of the directory file named 
[SMITH] on the device named DBAO:. 
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6.6.1 Sample Recursive Translation 

• Command 

$ DIRECTORY PROJECTS 

First table search (Looking for PROJECTS) 

"PROJECTS" = "DISKUSER: [ELLEN] " (LNM$PROCESSTABLE) 

Second table search (Looking for DISKUSER) 

"DISKOSER" = "DBAO:" (LNM$SYSTEMTABLE) 

Result 

DBAO: [ELLEN] - Searched 



Table 6-1 Commands for Displaying the Contents of Logical Name Tables 



Example 



$ SHOW LOGICAL 

S SHOW LOGICAL/FULL 

$ SHOW LOGICAL/PROCESS 
$ SHOW LOGICAL/ JOB 
$ SHOW LOGICAL/GROOP 
$ SHOW LOGICAL/SYSTEM 



Comments 



By default, displays logical names from the 
process, job-wide, group, and system logical 
name tables 

Displays all of the attributes of logical names 
from the process, job-wide, group, and system 
logical name tables 

Displays logical names from your process 
logical name table 

Displays logical names from your job-wide 
logical name table 

Displays logical names from your group 
logical name table 

Displays logical names from the system 
logical name table 
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$ SHOW LOGICAL/PROCESS 

(LNM$PROCESS_TABLE) 

"SYS$COMMAND" = "_DISK$RTA1 : " 
"SYS$DISK" = "DISK:" 
"SYS$ERROR" = "_DISK$RTA1 : " 
"SYS$INPUT" [super] = "_DISK:" 
"SYS$INPUT" [exec] = "_DISK$RTA1 : " 
"SYS$ODTPDT" [super] = "_DISK$RTA1 : " 
"SYS$OUTPUT" [exec] = "_D I SK$RTA1 : " 
"IT" = "RTA1: " 
$ SHOW LOGICAL/JOB 

(LNM$JOB_80392E4E40) 

"SYS$LOGIN" = "DISK: [HUBBARD] " 
"SYS$LOGINJDEVICE" = "DISK:" 
"SYS$REM_ID" = "HUBBARD" 
"SYS$REM_NODE" = "WHYSO::" 
"SYS$SCRATCH" = "DISK: [HUBBARD] " 
$ SHOW LOGICAL/GROUP 

( LNM$ GROUP_0 00011) 

"MY_DISK" = "DJAO:" 
$ SHOW LOGICAL/ SYSTEM 

(LNM$ SYSTEMJTABLE ) 

"DBG$INPUT" = "SYS$INPUT:" 

"DBG$OUTPUT" = "SYS$OUTPUT:" 

"DISK$WHYNOT_SYS" = "DISK:" 

"SYS$ANNOUNCE" = "Welcome to WHYNOT " 

"SYS$COMMON" = "DISK: [SYSO . SYSCOMMON. ] " 

"SYS$DISK" = "DISK:" 

"SYS$ERRORLOG" = " SYS$ SYSROOT : [SYSERR] " 

"SYS$HELP" = "SYS$SYSROOT: [SYSHLP] " 

"SYS$MAINTENANCE" = " SYS$ SYSROOT : [SYSMAINT] " 

"SYS$MANAGER" = "SYS$SYSROOT : [SYSMGR] " 

"SYS$MESSAGE" = "SYS$SYSROOT: [SYSMSG] " 

"SYS$NODE" = "WHYNOT::" 

"SYS$SYLOGIN" = "SYS$MANAGER: SYLOGIN.COM" 

"SYS$SYSDEVICE" = "DISK:" 

"SYSSSYSROOT" = "DISK: [SYSO .] " 

= "SYS$COMMON:" 
"SYS$SYSTEM" = "SYS$SYSROOT : [SYSEXE] " 
"SYS$UPDATE" = "SYS$SYSROOT: [SYSUPD]" 

Example 6-2 Displaying the Contents of the Process, Job, Group, and System Logical 
Name Tables 
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6.7 DETERMINING THE EQUIVALENCE OF A LOGICAL NAME 

There are two commands used to determine the equivalence of a logical name. 

The command SHOW LOGICAL logical-name translates iteratively up to 10 levels 
until everything is resolved. 

The command SHOW TRANSLATION logical-name displays the first equivalence 
string and then stops. No iteration is performed. 

$ ASSIGN DJAO: DISK1 

S ASSIGN DISK1: MYNAME 

$ SHOW TRANSLATION MYNAME 

MYNAME = "DISK1:" (LNM$PROCESS TABLE) 
$ SHOW LOGICAL MYNAME - 

"MYNAME" = "DISK1:" (LNM$PROCESS TABLE) 
1 "DISK1" = "DJAO:" (LNM$PROCESS_TABLE) 

Example 6-3 Determining the Value of a Logical Name 
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6.8 DELETING LOGICAL NAMES 

The DEASSIGN command deletes logical names from a particular logical name table. 
The qualifier /ALL can be used as well, depending upon how many logical names you 
want to delete. 

The following table lists examples of deleting logical names. 



Table 6-2 Commands for Deleting Logical Names 



Format/Examples 



Comments 



$ DEASSIGN[/table-name] [logical-name] 

$ DEASSIGN MYFILE 



$ DEASSIGN/ALL 

$ DEAS SIGH/ JOB 

$ DEASSIGN/GROUP OURFILE 

$ DEAS SIGN/ SYSTEM PAYROLL 



Deletes the logical name MYFILE from your 
process logical name table. 

Deletes all assignments that you have placed 
in your process logical name table. 

Deletes a logical name in your job table. 

Deletes the logical name OURFILE from 
your group logical name table. (This 
assumes you have GRPNAM privilege.) 

Deletes the logical name PAYROLL from the 
system logical name table. (This assumes 
you have SYSNAM privilege.) 
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Example 6-4 illustrates the manipulation of logical names. 

$ ASSIGN DJAO: DISK1 

$ ASSIGN DISK1: [HUBBARD] LOG 

$ SHOW LOGICAL/PROCESS 

(LNM$PROCESS_TABLE) 

"DISK1" = "DJAO:" 
"LOG" = "DISK1: [HUBBARD]" 
"SYS$COMMAND" = "_DISK:" 
"SYS$DISK" = "DISK:" 
"SYS$ERROR" = "_DISK$RTA1:" 
"SYS$INPUT" [super] = "_DISK:" 
"SYSSINPUT" [exec] = "_DISK$RTA1 : " 
"SYS$OUTPUT" [super] = "_DISK$RTA1 : " 
"SYS$OUTPUT" [exec] = "_DISK$RTA1: " 
"TT" = "RTA1:" 

$ ASSIGN DJA1: DISK1 

%DCL-I-SUPERSEDE, previous value of DISK1 has been superseded 

$ SHOW LOGICAL/PROCESS 

(LNM$PROCESS_TABLE ) 

"DISK1" = "DJA1:" 
"LOG" = "DISK1: [HUBBARD]" 
"SYS$ COMMAND" = "_DISK$RTA1 : " 
"SYS$DISK" = "DISK:" 
"SYS$ERROR" = "_DISK$RTA1 : " 
"SYS$INPUT" = "_DISK$RTA1:" 
"SYSSOUTPUT" [super] = "_DISK$RTA1 : " 
"SYS$OUTPUT" [exec] = "_DISK$RTA1 : " 
"TT" = "RTA1:" 

$ DEASSIGN/ALL 

$ SHOW LOGICAL/ PROCESS 

( LNM$ PROCE S S_T ABLE ) 

"SYS$COMMAND" = "_DISK$RTA1 : " 
"SYS$DISK" = "DISK:" 
"SYSSERROR" = "_DISK$RTA1:" 
"SYS$INPUT" = "_DISK$RTA1:" 
"SYS$OUTPUT" [super] = "_DISK$RTA1 : " 
"SYS$OUTPUT" [exec] = "_DISK$RTA1: " 
"TT" = "RTA1:" 



Example 6-4 Assigning, Changing, and Deleting Logical Name Assignments 
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6.9 SYSTEM-DEFINED LOGICAL NAMES 

When you log in, the system defines a number of logical names and stores them in your 
process logical name table. The system also creates a job-wide logical name table for 
your process and all of its potential subprocesses. A number of other logical names are 
denned and stored in the system logical name table at the time your system is initialized. 

You can override these permanently or temporarily with the ASSIGN or DEFINE 
commands previously discussed. 

Table 6-3 lists the logical name definitions you will use most often at your terminal. 



Table 6-3 Process Logical Names Defined by the System 



Logical Name 



SYS$COMMAND 

SYS$DISK 

SYS$ERROR 

SYS$OUTPUT 
SYS$INPUT 

TT 



Equivalence Name 



Original value of SYS$INPUT, equated to your terminal 
for interactive use and command procedures. 

Default disk established at login. Can be changed by the 
SET DEFAULT command. 

Default device to which the system writes messages. For 
an interactive user, the system equates SYS$ERROR to 
the terminal. 

Default output devices. For an interactive user, 
SYS$OUTPUT is equated to the terminal. 

Default input device. For all interactive use, SYS$INPUT 
is equated to the terminal. For command procedures, it is 
equated to the command file. 

Default device name for your terminal in interactive mode 
and for the console in batch mode. 
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Table 6-4 Job Logical Names Defined by the System 



Logical Name 



Equivalence Name 



SYS$LOGIN 



SYS$LOGIN_DEVICE 



SYS$SCRATCH 



Default disk and directory established at login time. This 
"home" directory is specified in the authorization record. 

Default disk established at login. Unlike the logical name 
SYS$DISK, SYS$LOGIN_DEVICE is not changed by the 
SET DEFAULT command. 

Default device and directory to which temporary files 
are written. For all use this is equated to your default 
directory. 



Table 6-5 System Logical Names Defined by the System 



Logical Name 



SYS$SYSTEM 

SYS$HELP 

SYS$LIBRARY 

SYS$MESSAGE 

SYSSSHARE 

SYS$SYSDEVICE 

SYS$NODE 



Equivalence Name 



Device and directory of operating system programs and 
procedures. 

Device and directory name of system help files. 

Device and directory name of system libraries. 

Device and directory name of system message files. 

Device and directory name of system shareable images. 

VMS system disk, device referred to in the system logical 
names listed above. 

Current network node name for the local system, if 
DECnet is active on the system. 
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6.9.1 SPECIFYING ACCuSS MODES 

You can specify a particular access mode by using /USER_MODE or /SUPER VISOR_ 
MODE in conjunction with the ASSIGN or DEFINE commands. 

User mode assignments last until the next image run in your process completes 
execution. (An image is a program in its executable form.) 

Supervisor mode (the default mode) assignments are in effect until: 

You log out 

You assign the particular logical name to a different equivalence string 

You remove the logical name assignment by using the DCL command DEASSIGN 

Note in Example 6-5 that SYS$OUTPUT, which by default is your terminal, has been 
redirected to the file named OUTPUT.LIS. The SHOW PROCESS command is issued, 
followed by the command TYPE OUTPUT.LIS to display the file OUTPUT.LIS at 
your terminal screen. 



$ ASSIGN/USER_MODE OUTPUT.LIS SYS$OUTPUT 

$ SHOW PROCESS 

$ TYPE OUTPUT.LIS 

22-OCT-1987 16:20:03.20 RTA1: User: SMITH 

Pid: 202001F8 Proc. name: SMITH UIC: [GROUP 11, SMITH] 

Priority: 4 Default file spec: DISK: [SMITH] 

Devices allocated: DISK$RTA1: 

$ 

Example 6-5 Using Logical Names to Alter the Default Output Device of Your Process 
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6.9.2 OVERRIDING DCL TABLE NAMES 

By default, both the ASSIGN and the DEFINE commands direct the system to make 
a logical name assignment in your process logical name table. To override this default, 
and make a logical name assignment in a table other than your process logical name 
table, use one of the following command qualifiers: 

/PROCESS (Default) 
• /JOB 

/GROUP (requires GRPNAM privilege) 
/SYSTEM (requires SYSNAM privilege) 

As mentioned earlier, logical name assignments in your process logical name table are 
known as process-private logical names. By default, logical name assignments in your 
user-defined logical name tables are also process-private logical names. Process-private 
logical names are in effect until you log out, unless you explicitly delete them. The 
shareable logical name assignments stored in your group and system logical name tables 
are not deleted when you log out 
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Table 6-6 describes the commands used for defining logical names. 



Table 6-6 Commands for Defining Logical Names 



Operation Format/Example 



Add or 
modify a 
logical name 
assignment 



$ ASSIGN [/mode-name] 
_Device: equivalence-name[,...] 
_log name: logical-name[:] 

$ ASSIGN DMAO: DISK 



$ DEFINE [/table-name] [/mode-name] 

_log name: logical-name[:] 

_equ name: equivalence-name[,...] 



Comments 



Assigns the equivalence string 
DMAO: to the logical name 
DISK. By default, the system 
stores the assignment in your 
process logical name table. 
(Note that you include the colon 
in the equivalence string, since it 
is part of the device name.) 



$ DEFINE DISK DMAO: 



Assigns the equivalence string 
DMAO: to the logical name 
DISK. By default, the system 
stores the assignment in your 
process logical name table. 
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Table 6-7 describes the commands used for displaying logical names. 



Table 6-7 Commands for Displaying Logical Names 



Operation Format/Example 

Determine 
the value 
of a logical 
name at 
command 
level 



$ SHOW LOGICAL logical-name 



$ SHOW LOGICAL MYFILE 



Comments 



Displays the translations for the 
logical name MYFILE found in 
the process, job-wide, group, and 
and system logical name tables. 



Determine 
the value 
of a logical 
name using a 
wildcard 



Determine 
the value 
of a logical 
name during 
an image 
interrupt 



$ SHOW LOGICAL SYS* 



$ SHOW TRANSLATION logical-name 



$ SHOW TRANSLATION DISK 



Displays the translations for all 
all logical names beginning with 
SYS in the process, job- wide, 
group, and system logical name 
tables, because of the use of the 
wildcard (*). 

Displays the equivalence 
string associated with Ihe first 
occurrence of DISK in your 
tables. (By default, the SHOW 
TRANSLATION command 
searches process, job-wide, 
group, and system tables, in that 
order.) 
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6.10 USING DCL SYMBOLS 

In addition to supporting logical names (which represent device, directory, and file 
specifications) the operating system supports a second facility for creating alternate 
names for commands or portions of command strings. Using a special command, 
called the assignment statement (=), you can assign values to symbols and store these 
assignments in special tables called symbol tables. You can use symbols created in this 
way as variables in command procedures and as command synonyms. 

The Writing Command Procedures module discusses the use of symbols as variables. 
This module covers the use of symbols as command synonyms. 

The left side of the assignment statement defines the symbol name. The right side of 
the assignment statement contains an expression that can be either an integer value or a 
character string. 

A symbol name can have a maximum of 255 characters. The symbol name must begin 
with a letter (A through Z), an underscore (_), or a dollar sign ($). After the first 
character, the name can contain any alphanumeric characters, underscores, and dollar 
signs. For example: 

$ COUNT =10 

$ RESULT == 100 

A command synonym is a name that represents character strings or numeric values. The 
portion of a command string equated to a command synonym is called its equivalence 
string. 

The global symbol table typically stores command synonyms and their equivalence 
strings. Each time you log in, the system creates both a global symbol table and a local 
symbol table for your process. You define, display, and delete command synonyms by 
entering DCL commands at your terminal. Figure 6-2 shows the relationship between 
your terminal, the operating system, and the symbol tables associated with your process. 
By defining command synonyms, you can create your own command language and 
simplify your terminal sessions. 
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DCL places local symbols in the local symbol table. A local symbol exists as long as 
the command level remains active. A local symbol is defined by using a single equal 
sign (=) in the assignment statement 



$ TEST = "HELLO" 



Global symbols are placed in the global symbol table. A global symbol exists for the 
duration of the process, unless it is specifically deleted. A global symbol is defined by 
using two equal signs (==) in the assignment statement: 



$ RESULT == 50 

You can also abbreviate the symbol forms by use of the asterisk (*) as the abbreviation 
indicator. For example, to abbreviate a local symbol to invoke the Mail utility: 

$ M*AIL = "MAIL" 

The Mail utility will be invoked using any of these abbreviations: "M" "MA" "MAI" 
and "MAIL". 
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Figure 6-2 The Relationship Between Your Terminal, the Operating System, and Your Global 
Symbol Table 



6-26 CUSTOMIZING THE USER ENVIRONMENT 



6.10.1 Deleting Symbol Definitions 

Symbol definitions are deleted from a symbol table by using the DELETE/SYMBOL 
[symbol-name] command. If you do not specify the name of a symbol table the symbol 
definition is deleted from the local symbol table. 

There are three qualifiers that can be used in conjunction with the DELETE/SYMBOL 
command. They are: 

• /LOCAL - Specifies that the symbol name is to be deleted from the local symbol 
table. 

• /GLOBAL - Specifies that the symbol name is to be deleted from the global 
symbol table. 

• /ALL - Specifies that all symbol names in the specified symbol table be deleted. 
If neither /LOCAL or /GLOBAL are specified, all symbols defined at the current 
command level are deleted. 
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Table 6-8 describes the commands used for defining, displaying, and deleting symbols. 



Table 6-8 Commands for Defining, Displaying, and Deleting DCL Symbols 



Operation Format/Example 



Comments 



Defining a $ symbol-name = = "equiv-string" 
DCL Symbol s to == "set default" 



Assigns the equivalence 
string SET DEFAULT 
to the symbol TO, 
storing the definition 
in your global symbol 
table 



Displaying Symbols 



Displaying 
a Single 
Symbol 

Displaying 
All Symbols 



$ SHOW SYMBOL/GLOBAL symbol-name 

$ SHOW SYMBOL/GLOBAL TO 



$ SHOW SYMBOL/GLOBAL/ALL 



Displays the value of 
the symbol TO 



Displays the values 
of all symbols defined 
in your global symbol 
table 



Displaying 
All Symbols 
Using a 
Wildcard 



$ SHOW SYMBOL/ GLOBAL S* 



Displays the values 
of all symbols defined 
in your global symbol 
table beginning with 

the letter "s" 



Deleting Symbols 



Deleting 
a Single 
Symbol 

Deleting All 
Symbols 



$ DELETE/SYMBOL/GLOBAL symbol-name 

S DELETE/ SYMBOL/GLOBAL TO 



$ DELETE/ SYMBOL/GLOBAL/ALL 



Deletes the symbol 
TO from your global 
symbol table 

Deletes all symbols 
from your global 
symbol table 
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$ DIRP == "DIRECTORY/OWNER/PROTECTION" 
$ TO == "SET DEFAULT" 
$ RETURN == "SET DEFAULT SYS$LOGIN" 
$ LOCALS == "SHOW SYMBOL/LOCAL/ALL" 
$ GLOBALS == "SHOW SYMBOL/GLOBAL/ALL" 
$ DEL_SL == "DELETE/SYMBOL/LOCAL" 
$ DEL_SG == "DELETE/SYMBOL/GLOBAL" 
$ GLOBALS 

$RESTART == "FALSE" 

$ SEVERITY = "1" 

$STATUS = "%X00030001" 

C*LEAR == "RUN SYS $ SYSTEM: ERASE" 

DEL_SG == "DELETE/SYMBOL/GLOBAL" 

DEL_SL == "DELETE/SYMBOL/LOCAL" 

DIRP == "DIRECTORY/OWNER/PROTECTION" 

GLOBALS = "SHOW SYMBOL/GLOBAL/ALL" 

LOCALS == "SHOW SYMBOL/LOCAL/ALL" 

RETURN == "SET DEFAULT SYS$LOGIN" 

TO = "SET DEFAULT" 
$ TO SYS$SYSTEM 
$ DIRP DCL.EXE 
Directory SYS$COMMON: [SYSEXE] 

DCL.EXE; 1 [SYSTEM] (RWED,RWED, RWED, RE) 

Total of 1 file. 

$ RETURN 
$ DEL_SG/ALL 
$ GLOBALS 

%DCL-W-IWERB, unrecognized command verb - check validity and spelling 
\GLOBALS\ 



Example 6-6 Defining, Displaying, and Deleting Symbols 
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Table 6-9 compares various aspects of logical names and symbols. 



Table 6-9 Comparison of Logical Names and DCL Symbols 



Characteristic 



Logical Names 



Symbols 



Function 



Usage 



Storage 



Definition 



Display 



Represent device, directory, and 
file specifications. 

Used in place of any complete 
device, directory, or file 
specification. Also used in 
place of any contiguous group 
of left-hand fields in a file 
specification. Must occur as part 
of a command string parameter 
to be passed to the file system 
for translation. 

Stores assignments in your 
process, job, group, or system 
logical name table. 

Either the ASSIGN or DEFINE 
command 

Either the SHOW LOGICAL 
or SHOW TRANSLATION 
command. 



Represent commands or portions of 
command strings. 

Used in place of any complete 
command string. Also used in 
place of any left-hand portion of a 
command string. Must occur as the 
first word in a command string to be 
translated by the command language 
interpreter. 



Stores assignments in your global or 
local symbol table. 



An assignment statement (=) or 
(==)• 

The SHOW SYMBOL command. 



Deletion 



The DEASSIGN command. 



The DELETE/SYMBOL command. 
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6.11 DEFINING KEYS 

As you become more familiar with the VMS system, you will find that you are 
repeatedly entering certain commands. You can reduce the amount of typing required 
to one keystroke. Use the DEFINE/KEY command, which assigns a definition to a 
keyboard key. Definitions often contain part or all of a DCL command string. 

The types of terminals and their associated definable keys are: 

• VT52-series terminals - All definable keys located on the numeric keypad 

• VTlOO-series terminals - All keys located on the numeric keypad plus the LEFT 
and RIGHT ARROW keys 

• Terminals with LK201 keyboards - All keys on the numeric keypad; keys on the 
editing keypad (except the UP and DOWN ARROW keys); keys on the function 
key row across the top of the keyboard (except Function keys Fl through F5) 

Keys KPO - KP9, PERIOD, COMMA, and MINUS must be enabled for definition 
purposes. These keys are enabled by using either of the following commands: 

$ SET TERMINAL/APPLICATION_KEYPAD 
$ SET TERMINAL/NONUMERIC 

Keypad keys PF1 - PF4 can also be defined. 

The format is: 

$ DEFINE/KEY key-name equivalence string /qualifiers 
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One or more of the following qualifiers can be used to alter the action of a denned key: 

/TERMINATE - Produces an automatic return 

/NOECHO - Suppresses the display of the command being invoked 

/ERASE - Erases the characters on the current line before displaying and executing 
the command invoked by the defined key 

/NOLOG - Suppresses the informational message you receive when you initially 
define a key 

Example: 

$ DEFINE/KEY PF3 "SHOW PROCESS" /TERMINATE 

Now that key PF3 has been defined. Each time you press that key, the DCL command 
SHOW PROCESS will be executed. Note that the qualifier /TERMINATE is used to 
signify that the equivalent string (SHOW PROCESS) will be executed when key PF3 
is pressed. 
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6.11.1 Displaying a Key Definition 

To display a key definition, issue (he DCL command: 

$ SHOW KEY/FOLL key- name 

Example: 

$ SHOW KEY/FOLL PF3 
PF3 = "show process" 
(echo, terminate, noerase, nolock) 

6.11.2 Removing a Key Definition 

To remove a key definition, use the DELETE/KEY command. The following command 
removes the definition applied to the PF3 key: 

$ DELETE/KEY PF3 

%DCL-I-DELKEY, HOME key PF3 has been deleted 

You can use the qualifier /ALL to delete all key definitions in the current state. If you 
use the qualifier /ALL, do not specify a key name. 

$ DELETE /KEY/ ALL 

If keys PF1 through PF4 had been defined in the DEFAULT state, you would get a 
message on the terminal screen stating that keys PF1 through PF4 had been deleted. 

The following section describes how you can add different states to a key definition. 
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6.11.3 Assigning Multiple Definitions to Keys 

You can assign any number of definitions to a key by assigning each definition to a 
different key state. For example: 

$ DEFINE/KEY PF1 "SHOW " SETSTATE=GOLD/NOTERMINATE/ECHO 
$ DEFINE/KEY PF1 " PROCESS" /TERMINATE/ IF_STATE=GOLD/ECHO 

The first time you press the PF1 key, the system echoes the string "SHOW " at your 
terminal and sets the state of the PF1 key to GOLD. The second time you press the PF1 
key, the system: 

Tests the key state (GOLD) 

Displays the string " PROCESS" (Appends the string " PROCESS" to the string 
"SHOW ") 

Passes the entire command to the command language interpreter for processing 

NOTE 

If a key is defined and the qualifier SET_STATE is not used, then the key 

state is DEFAULT. 
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$ DEFINE/KEY PF1 "SHOW " /SET_STATE=GOLD/NOTERMINATE/ECHO 
$ DEFINE/KEY PF1 " PROCESS" /TERMINATE/ IF_STATE=GOLD/ECHO 

Example 6-7 Defining Multiple Definitions for One Key 
Notes on Example 6-7: 

1. The qualifier /SET_STATE=state-name causes the specified state name to be set. 
The state name can be any alphanumeric string. In this case, the state name is 
GOLD. 

2. The qualifier /IF_STATE=state-name determines whether or not a previously 
defined state name is in effect, in order for the key definition to be in effect. 

3. The qualifier /NOTERMINATE allows you to create key definitions that insert 
text in command lines. In this particular example, using the /TERMINATE 
qualifier would have the first key definition echo the word "SHOW" but not the 
following word "PROCESS". 

4. The qualifier /ECHO determines whether the equivalence string is displayed on 
the terminal screen when the key is pressed. 
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6.12 SUMMARY 

A logical name is a name you can use in place of all or part of a file specification 

• They are used to: 

— Achieve device and file independence in programs or procedures 

Reduce typing and improve readability (used as replacement for long file 

specifications) 

Pass data among programs, or between a command procedure and a program 

Logical names and their equivalence strings can each have a maximum of 255 
characters (including alphanumeric characters, dollar signs and underscores) 

Any other characters must be enclosed in quotation marks 

• Stored in logical name tables 
System Denned Logical Names 
When you log in, the system: 

Defines a number of logical names and stores them in your process logical name 
table 

Creates a job-wide logical name table for your process and all of its potential 
subprocesses 

You may override these permanently or temporarily with the ASSIGN or DEFINE 
commands 

DCL Symbols 

Symbols are names that represent character strings or numeric values 

Can be used as DCL command synonyms allowing the user to tailor DCL command 
format 

Equated to an equivalence string (which is enclosed in " ") 

— Complete command string 

— Portion of a command string 

Stored in one of two tables (each process has its own) 

— LOCAL 

— GLOBAL 
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Defining Keys 

Definitions often contain part or all of a DCL command string 
Reduces typing of lengthy or frequently used DCL commands 

Syntax: 

$ DEFINE/KEY key-name equivalence string /qualifiers 

To display a key definition, issue the DCL command: 

SHOW KEY/FULL key-name 

To delete a key definition, issue the DCL command: 

DELETE/KEY key-name 
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0.1 3 WRii inN nXEis.^ibE i 

Write the letter of the system-defined logical name that best fits each of the device 
and directory descriptions on the following page. Some answers require more than one 
letter. 



System-Defined Logical Names 


a. 


SYS$COMMAND 


b. 


SYS$DISK 


c. 


SYS$ERROR 


d. 


SYS$HELP 


e. 


SYS$INPUT 


f. 


SYSSLIBRARY 


g- 


SYS$LOGIN 


h. 


SYS$NODE 


i. 


SYS$OUTPUT 


J- 


SYSSSYSDEVICE 


k. 


SYSSSYSTEM 
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Device and Directory Descriptions 

1- Specifies the default device to which the system writes output during a 

terminal session. 

2 - Specifies the default device to which the system writes messages during a 

terminal session. 

3. Specifies your default disk. 

4 - Specifies the directory in which help files are cataloged. 

5 - Specifies the directory in which system libraries are cataloged. 

6. Specifies your default user file directory (UFD). 

7 - Specifies the device from which the command language interpreter and 

utility programs read input during a terminal session. 

8- Specifies the directory in which operating system programs and procedures 

are cataloged. 

9- Specifies your terminal during an interactive process. 

10- Specifies the disk on which system programs and routines are stored. 

11- Specifies the name of the current network node. 
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Write the letter of the symbolic name type that best fits each of the following 
characteristics. 

Symbolic Name Type 

a. Command Synonym 

b. Logical Name 

Characteristic 

1. Represents device, directory, and file specifications 

2. Translated by the file system 

3. Translated by the command language interpreter 

4. Defined by the direct assignment statement (=) 

5. Deleted by the DEASSIGN command 

6. Displayed by the SHOW SYMBOL command 

7. Defined by the ASSIGN command 

8. Represents commands and command strings 

9. Deleted by the DELETE/SYMBOL command 
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6. 15 LABORATORY EXERCISE I 

Complete each of the following exercises at an interactive terminal. Display only one 
logical name table for each exercise. 

1. Display at your terminal the contents of the logical name table used by your 
process. This particular logical name table contains process-private logical names. 

2. Display at your terminal the contents of the logical name table used by your 
process and its subprocesses. This particular logical name table contains shareable 
logical names. 

3. Display at your terminal the contents of the logical name table used by your UIC 
group member processes. This particular logical name table contains shareable 
logical names. 

4. Display at your terminal the contents of the logical name table used by all system 
processes. This particular logical name table contains shareable logical names. 

5. Create a logical name for your default directory. 

a. Check the proper logical name table to make sure your newly created logical 
name exists 

b. Use the logical name in conjunction with the DIRECTORY command to 
view the file names in your default directory 

c. Delete your newly created logical name after correcdy performing this 
exercise. 
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Complete each of the following laboratory exercises at an interactive terminal. 

1. Create a subdirectory 

2. Create a logical name for a text file in your default directory 

3. Create a logical name for your newly created subdirectory 

4. Using only logical names, move the text file into your new subdirectory 

5. After completing this exercise, remove the above logical names 
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6. 17 LABORATORY EXERCISE IH 

Create global symbols to perform the following tasks. You can create these global 
symbols interactively or in the file LOGIN.COM. 

1. Display a directory and size of all files in your directory 

2. Show the time of day 

3. Display all global symbols at your terminal 

4. Move to another default directory 

5. Return to your original default directory 

To correct mistakes you may have made when you defined a DCL symbol, use the 
DELETE/SYMBOL command to remove the faulty definition, then enter it again. 
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6.18 WRTTTEJN hXck^i^jc i — dui^uiiwINo 

Write the letter of the system-defined logical name that best fits each of the device 
and directory descriptions on the following page. Some answers require more than one 
letter. 

System-Defined Logical Names 

a. SYS$COMMAND 

b. SYS$DISK 

c. SYS$ERROR 
d SYSSHELP 

e. SYS$INPUT 

f. SYS$LIBRARY 

g. SYS$LOGIN 
h. SYS$NODE 

i. SYS$OUTPUT 
j. SYS$SYSDEVICE 
k. SYS$SYSTEM 
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Device and Directory Descriptions 

1- i Specifies the default device to which the system writes output during a 

terminal session. 

2. c Specifies the default device to which the system writes messages during a 

terminal session. 

3. b Specifies your default disk. 

4. d Specifies the directory in which help files are cataloged. 

5. f Specifies the directory in which system libraries are cataloged. 

6. g Specifies your default user file directory (UFD). 

7. e Specifies the device from which the command language interpreter and 

utility programs read input during a terminal session. 

8. k Specifies the directory in which operating system programs and procedures 

are cataloged. 

9. a,c,e,i Specifies your terminal during an interactive process. 

10. j Specifies the disk on which system programs and routines are stored. 

11. h Specifies the name of the current network node. 
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6.19 WRITTEN EXERCISE II— SOLUTIONS 

Write the letter of the symbolic name type that best fits each of the following 
characteristics. 

Symbolic Name Type 

a. Command Synonym 

b. Logical Name 

Characteristic 

1. b Represents device, directory, and file specifications 

2. b Translated by the file system 

3. a Translated by the command language interpreter 

4. a Defined by the direct assignment statement (=) 

5. b Deleted by the DEASSIGN command 

6. a Displayed by the SHOW SYMBOL command 

7. b Defined by the ASSIGN command 

8. a Represents commands and command strings 

9. a Deleted by the DELETE/SYMBOL command 
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6.20 LABORATORY EXERCISE I— SOLUTIONS 

Complete each of the following exercises at an interactive terminal. Display only one 
logical name table for each exercise. 

1. Display at your terminal the contents of the logical name table used by your 
process. This particular logical name table contains process-private logical names. 



$ SHOW LOGICAL/PROCESS 



2. Display at your terminal the contents of the logical name table used by your 
process and its subprocesses. This particular logical name table contains shareable 
logical names. 

S SHOW LOGICAL/ JOB 

3. Display at your terminal the contents of the logical name table used by your UIC 
group member processes. This particular logical name table contains shareable 
logical names. 

$ SHOW LOGICAL/GROUP 

(There may not be any logical names denned in this table.) 

4. Display at your terminal the contents of the logical name table used by all system 
processes. This particular logical name table contains shareable logical names. 

$ SHOW LOGICAL/SYSTEM 
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$ ASSIGN W0RK2 :[ SMITH] MYDIR 

a. Check the proper logical name table to make sure your newly created logical 
name exists 

$ SHOW LOGICAL MYDIR 

"MYDIR" = "W0RK2: [SMITH]" (LNM$PROCESS_TABLE) 

b. Use the logical name in conjunction with the DIRECTORY command to 
view the file names in your default directory 

$ DIRECTORY MYDIR 

Directory W0RK2 : [ SMITH] 

CALENDAR.EXE; 1 CLASS. LIST;4 CLOCK.EXE;! DEG.EXE;1 

JOE_EVE. TPU$ SECTION ;1 KEYS. COM; 5 L0GIN.COM; 6 

MAIL.DIR;1 PERSONAL . LGP ; 4 REMLOG.EXE;l T0D0.DAT;17 
UTL.DIR;1 WEEKDAY . EXE ; 1 

Total of 13 files. 

c. Delete your newly created logical name after correctly performing this 
exercise. 

$ DEASSIGN/ALL 

Or $ DEASSIGN/PROCESS MYDIR 
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6.21 LABORATORY EXERCISE U— SOLUTION 

Compare your results with the following example. 

$ CREATE /DIRECTORY/LOG [SMITH. TEXT] 

%CREATE- I -CREATED, DISK: [SMITH. TEXT] created 

$ ASSIGN [SMITH. TEXT] MY_TEXT 
$ ASSIGN MYFILE.TXT; 1 OUTPUT 

$ SHOW LOGICAL/PROCESS 

(LNM$PROCESS_TABLE) 

"MY_TEXT" = " [SMITH. TEXT ] " 
"OUTPUT" = "MYFILE.TXT; 1" 
"SYS$COMMAND" = "_DISK$RTA1 : " 
"SYS$DISK" = "DISK:" 
"SYSSERROR" = "_DISK$RTA1:" 
"SYSSINPUT" = "_DISK$RTA1 : " 
"SYS$OUTPUT" [super] = "_DISK$RTA1 : " 
"SYS$ODTPUT" [exec] = "_DISK$RTA1: " 
»TT" = "RTA1:" 

$ COPY/LOG OOTPDT MY_TEXT 

%COPY-S-COPIED, DISK: [SMITH] MYFILE.TXT; 1 copied to 
DISK: [SMITH. TEXT] MYFILE.TXT; 1 (1 block) 

$ DEASSIGN OUTPUT 
$ DEASSIGN MY_TEXT 
$ 
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6.22 LABORATORY EXERCISE HI— SOLUTIONS 

Create global symbols to perform the following tasks. You can create these global 
symbols interactively or in the file LOGIN.COM. 

1. Display a directory and size of all files in your directory 

$ DS == "DIRECTORY/SIZE" 

2. Show the time of day 

$ TIME == "SHOW TIME" 

3. Display all global symbols at your terminal 

$ GLO == "SHOW SYMBOL/ GLOBAL/ALL" 

4. Move to another default directory 

$ MOVE == "SET DEFAULT" 

5. Return to your original default directory 

$ RETURN == "SET DEFAULT SYS$L0GIN" 
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7,1 INTRODUCTION 

As you become a more experienced user, you will begin to notice that certain commands 
are used repeatedly, in exactly the same order. Typing in these commands at the terminal 
can be tedious and time-consuming. 

Command procedures provide you with a means to execute these commands 
automatically. 

Command procedures are files consisting of DCL commands. In addition to the 
command verbs, qualifiers and parameters commonly used at the interactive level, 
there are several DCL command language features that provide power and flexibility, 
including: 

• Symbols that can be used as numeric and string variables 
Instructions that allow you to control program flow 

• Lexical functions 

This module presents the material needed to create, test, and run a command procedure 
interactively. The Submitting Batch and Print Jobs module shows you how to run 
command procedures independently of your interactive process, as batch jobs. 
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7.2 OBJECTIVES 

To write DCL command procedures, you should be able to: 

Define what a command procedure is and describe why command procedures are 
used 

Create a command procedure, using standard DCL command elements 

• Control terminal input and output in a command procedure by: 

— Displaying messages on the terminal 

— Accepting input from the user 

— Redirecting input or output from the terminal to another location 

• Pass data to a command procedure using parameters 

Control the flow of execution within a command procedure using: 

— The IF command 

— The GOTO command 

• Use the proper lexical function to obtain the information needed in a command 
procedure 

7.3 RESOURCES 

• Guide to Using VMS Command Procedures 
VMS DCL Dictionary 
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7.4 COMMAND PROCEDURES 

A command procedure is a file containing DCL command strings. Command strings in 
a command procedure are made up of DCL command verbs, command qualifiers, and 
parameters. 

In addition to DCL commands, command procedures frequently make use of DCL 
command language features such as: 

• Symbols, which can be used as command synonyms, or as numeric or string 
variables 

• Control flow statements, similar to branching commands in programming languages 

• Lexical functions, which provide information about the system, processes, and files 

7.4.1 Common Uses 

Command procedures have several uses. One use is the repeated execution of a group 
of instructions. Instead of entering the commands at the interactive level, you can 
execute the commands in a command procedure, saving time and typing. A command 
procedure can be used by several people, ensuring consistency of action, and reducing 
duplication of effort. 

Command procedures are also helpful when you must use long or complicated command 
strings. Command procedures help assure that the syntax of these commands is correct. 

Finally, command procedures are used when you want to run a job in batch mode. When 
you submit a command procedure to be run in batch mode, you free your terminal for 
other tasks. The use of batch queues is discussed in the Submitting Batch and Print 
Jobs module later in this course. 
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7.4.2 Developing a Command Procedure 

The steps to develop a command procedure are similar to steps used to develop a 
computer program in any language. 

1. Design the command procedure. 

• Determine what tasks the procedure should perform. 
Decide what results the procedure should produce. 

2. Create the command procedure. 

• Use the text editor of your choice. 

Specify the file type COM for the command procedure. 

3. Execute and test the command procedure. 

Use the "at sign" (@) to execute the procedure interactively. 
Use the DCL command SET VERIFY to: 

— Display each line of the procedure as it executes. 

— Help locate errors if they occur. 

4. Modify and retest the command procedure, if necessary. 

• Repeat steps 2 and 3. 

Use the DCL command SET NOVERIFY after the procedure has been 
tested and perfected. 

5. Add comments to the command procedure so it is easy to read and maintain 
Comments should describe: 

The procedure in detail. 

• Any parameters that are passed to the procedure. 
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DEVELOPMENT STEP 



DESIGN PROCEDURE 




v 




WRITE PROCEDURE 




' 


' 




TEST PROCEDURE 


















MODIFY PROCEDURE 


' 


' 


n 


<^ DID IT WORK? ^> 




RE-TEST PROCEDURE 

USING 

$ SET VERIFY 





CORRESPONDING DCL 
COMMAND {IF ANY) 



NONE 



$ EDIT filename.COM 



$ (©filename. COM 



$ EDIT filename.COM 



$ SET VERIFY 
$ ©filename. COM 



' 


' 


ADD COMMENTS 
TO PROCEDURE 



$ EDIT filename.COM 



TTB X0335 88 



Figure 7-1 Command Procedure Development Process 
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7.5 COMPONENTS AND CONVENTIONS 

Consistent format and clear programming style make your command procedures easy to 
read, test, and maintain. 

7.5.1 DCL Command Lines 

Always use full command verbs. Do not use abbreviations. Abbreviated commands 
may become ambiguous if a new DCL command verb is added. 

Precede each command line with the $ prompt. Although you can change your DCL 
prompt at the interactive level, the dollar sign prompt is still used to indicate a command 
line within a procedure. 

You can continue a line by placing a hyphen at the end of the line. Do NOT begin the 
continued line with a dollar sign. 

7.5.2 Data Lines 

Data lines can be used to include information used by the procedure or by another 
utility. When data lines are used, they are placed immediately after the command that 
will use them. Do NOT place a dollar sign at the beginning of a data line. Data input 
is terminated by the first occurrence of a dollar sign, and control is transferred back to 
the command procedure. 

7.5.3 Comments 

An exclamation point (!) indicates a comment When the system encounters an 
exclamation point it immediately goes on to the next line. Everything following the 
exclamation point is ignored. 

It is recommended that you use blank comment lines ($!) to separate blocks of 
instructions. 



7.5.4 Labels 

Labels are the names of locations within the command procedure. Like DCL commands, 
labels must be preceded by a $. In addition, labels must be followed by a colon (:). For 
better readability, no command should be placed on the same line as the label. 
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REPORTl.COM 



This command procedure sets your default directory 

to the REPORTS. MONDAY subdirectory, prints out a report for 

Monday, returns you to your login device and 

directory, then exits. 



Set your default to the REPORT S.MONDAY subdirectory 

SET DEFAULT DISK1: [REPORT S.MONDAY] 

Print out the report for Monday 

PRINT MONDAY. RPT 

Return to your login device and directory 

SET DEFAULT SYS$L0GIN 
EXIT 



Execution of REP0RT1.COM: 

$ @REP0RT1 

DISK1: [REPORTS. MONDAY] 

Job MONDAY (queue SYS$PRINT, entry 44) started on WORK$TXA0 



Example 7-1 A Sample Command Procedure 
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Now try it with VERIFY tamed on: 



$ SET VERIFY 

$ 

$ 9 REPORT 1 

$ 

$ 
$ 

s 
s 
$ 
$ 
$ 
$ 
$ 
$ 
$ 
$ 
$ 
$ 

$ PRINT MONDAY. RPT 

Job MONDAY (queue SYS$PRINT entry 46) started on WORKSTXA0 

§ ! 

$ ! Return to your login device and directory 

$ ! 

$ SET DEFAULT SYS$LOGIN 

$ EXIT 

Example 7-1 (Cont.): A Sample Command Procedure 
Notes on Example 7-1: 



REPORTl.COM 



This command procedure sets your default directory 

to the REPORT S.MONDAY subdirectory, prints out a report for 

Monday, returns you to your login device and 

directory, then exits . 



Set your default to the REPORTS. MONDAY subdirectory 
SET DEFAULT DISK1 : [REPORTS. MONDAY] 
Print out the report for Monday 



1. 
2. 



This is a very simple command procedure. Its purpose is to display some good 
programming practices you can use when you write command procedures. 

Comment lines, added to your procedure, help you and others to determine the 
procedure's function, and to simplify maintenance. Note that comment lines are 
indicated by a dollar sign followed by an exclamation point ($!). 

Each DCL command in the procedure is fully spelled out. By avoiding 
abbreviations, you avoid possible ambiguities when new DCL commands are 
added. 
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7.6 LOGIN COMMAND PROCEDukE 

This is a command procedure that is executed automatically each time you log in. The 
name of the file must be LOGIN.COM and be placed in your default login directory. 

This file contains logical names, symbols, and other commands you may have denned 
to set up your terminal session. 

The example on the following page shows a typical LOGIN.COM file. 

Notes on Example 7-2: 

1 . This procedure runs automatically when you log in. 

2. The procedure is commented, and similar commands are grouped together. This 
helps make the procedure easier to read and maintain. 

3. Global symbols are created that can be used as command synonyms to reset the 
user's default directory. Instead of using the SET DEFAULT command, the user 
can enter these symbols at the DCL prompt. 

4. Command synonyms are created for commonly used DCL commands, by assigning 
global symbol values to the selected DCL commands. 

5. The DEFINE command is used to assign command values to keypad keys. 
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$ 
S 
$ 
$ 
$ 
$ 

$ 
$ 
$ 
$ 
$ 
$ 
$ 
$ 
$ 
$ 
$ 
$ 
$ 
$ 
s 
s 
$ 
s 
$ 
$ 
$ 
$ 
s 
s 
$ 
$ 
$ 
$ 



LOGIN.COM 



Logical names for common files and directories 

ASSIGN SYS$LOGIN_DEVICE: [BLOOM. PASCAL] PASCAL 

ASSIGN SYS$LOGIN_DEVICE: [BLOOM. GAMES] FUN 

ASSIGN SYS$LOGIN_DEVICE: [BLOOM. PROCEDURES] CLEANaP.COM CLEANUP 



Commonly used commands 

SED == "SET DEFAULT" 

HOME == "SET DEFAULT SYSSLOGIN" 

CLR = "SET TERMINAL/WIDTH=80" 

EDT == "EDIT" 

DS == "DIRECTORY/SIZE=ALL" 

SD == "SHOW DEFAULT" 

M == "MAIL" 

PU == "PURGE/LOG" 

XX == "DELETE" 



Key definitions 

SET TERMINAL/APPLICATION_KEYPAD 

DEFINE/KEY/NOLOG/TERMINATE PF1 "SHOW USERS" 
DEFINE/KEY/NOLOG/TERMINATE PF3 "SHOW TIME" 

DEFINE/KEY/NOLOG/TERMINATE KP9 "SHOW QUEUE/ALL/FULL LPAO" 
DEFINE/KEY/NOLOG/TERMINATE KPO "LOGOUT" 

EXIT 



Example 7-2 Typical L0GIN.COM File 
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TERMINAL INPUT/OUTPUT 

Several DCL commands allow you to perform terminal input and output operations 
from within a command procedure. Some of these commands allow you to prompt the 
user for information that can be used by the procedure. Other commands allow you to 
display messages and command output on the terminal screen. 

These commands make use of predefined logical names. By redefining these logical 
names, you can allow the use of an interactive utility, like an editor, from within the 
procedure, or redirect terminal output to a file. 

Table 7-1 lists the logical names used with terminal input and output commands. Notice 
that these logical names usually point to your terminal. 

When you execute a command procedure, one logical name, SYS$INPUT, is 
automatically defined to point to the command procedure file, rather than your terminal. 
This means that the system looks for its input from the command procedure file, rather 
than from the terminal. To allow for input to be entered from the terminal (for example, 
to edit a file), you must redirect the logical SYS$INPUT so that it points to the terminal. 

Table 7-2 lists commands that display information on your terminal. Table 7-3 lists 
commands that prompt the user for information. Table 7-4 lists commands that redirect 
terminal input and output 
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Table 7-1 System Logical Names Used with Terminal I/O 



Logical Name 



Description 



Associated File or Device 



SYS$COMMAND Initial input stream for 
your process 



(At Login) 



Terminal 



SYS$INPUT 

SYS$OUTPUT 

SYS$ERROR 



Default input stream for Terminal 
your process 

Default output stream for Terminal 
your process 



Default file to which 
the system writes error 
messages 



Terminal 



(During 

Execution 

of a Procedure) 



Terminal 



Command 
Procedure File 

Terminal 



Terminal 
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7.7.1 Performing Terminal Input and Output 



Table 7-2 Displaying Information on the Terminal 



Format/Example 



$ WRITE SYS$OUTPUT string 

$ WRITE SYS$OUTPUT "Hello." 

$ WRITE SYS$OUTPUT symbol 

$ WRITE SYS$OUTPUT PI 

$ TYPE SYS$INPUT 

text 

text 

text 

$ 

$ TYPE SYS$ INPUT 

Hello 

$ 



Comments 



Character strings are enclosed in quotation 
marks. 

The symbol's value is automatically 
substituted. 

Information to be displayed follows the TYPE 
command. A dollar sign marks the end of the 
information. 
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$ 
$ 
$ 
$ 
$ 
$ 
$ 
$ 
$ 
$ 
$ ! 



REP0RT2 . COM 



This command procedure sets your default directory to the 
[REPORTS. MONDAY] subdirectory, prints out a report for Monday, 
returns you to your login device and directory, then exits. 

WRITE SYS$OUTPUT "" 

WRITE SYS$OUTPUT "Changing your default directory" 



$ ! Set your default to the correct subdirectory 

$ ! 

$ SET DEFAULT DISK1 : [REPORTS .MONDAY] 

$ ! 

$ WRITE SYS$OOTPUT "" 

$ WRITE SYS$OUTPUT "Printing the Monday report" . 

$ ! 

$ ! Print out the report for Monday 

$ ! 

$ PRINT MONDAY. RPT 

$ ! 

$ ! Return to your login device and directory 

$ ! 

$ WRITE SYS$OUTPUT "" 

S WRITE SYS$OUTPUT "Changing back to your login directory" 

$ ! 

S SET DEFAULT SYS$LOGIN 

$ EXIT 

Execution of REPORT2.COM: 

$ ©REP0RT2 

Changing your default directory 

Printing the Monday report 

Job MONDAY (queue SYSSPRINT, entry 46) started on WORK$TXA0 

Changing back to your login directory 



Example 7-3 An Output Sample from a Command Procedure 
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Notes on Example 7-3: 

1. The WRITE SYS$OUTPUT commands display the character string you specify 
on the terminal screen. 

2. The SET DEFAULT DISKl:[REPORTS.MONDAY] command sets your default 
to the correct subdirectory. 

3. The DCL command PRINT MONDAY.RPT prints the correct report. 

4. The DCL command SET DEFAULT SYS$LOGIN returns you to your default 
device and directory and then you exit from the command procedure. 
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Table 7-3 Getting Information from the User 



Format/Example 



$ INQUIRE symbol "prompt" 

S INQUIRE NAME "Filename" 



Comments 



$ READ/PROMPT=string SYS$COMMAND symbol 

$ READ/PROMPT="Filename: " SYS$COMMAND NAME 



The prompt string is 
optional. The user's 
response is converted to 
uppercase. Multiple blanks 
and tabs are replaced with a 
single space. The response 
is then assigned to the local 
symbol "Filename." If no 
prompt string is supplied, 
the symbol name is used as 
the prompt. 

The user's response is not 
converted to uppercase, 
and multiple spaces are not 
removed. The response 
is then stored in the local 
symbol "Filename." 
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Table 7-4 Redirecting Input and Output 



Format/Example 



$ DEFINE/USER_MODE SYS$ INPUT SYS$COMMAND 

or 

$ ASSIGN/USER_MODE SYS$COMMAND SYS$ INPUT 



$ @commandfile-name/ OUTPUT=output-file-name 



$ @COMFILE.COM/OUTPUT=COMSTAT.DAT 

$ DEFINE/USER_MODE SYS$OUTPUT output-file-name 

or 

$ ASSIGN/USER_MODE output-file-name SYS$OUTPUT 
$ DEFINE/USER_MODE SYS$OUTPUT COM_STAT.DAT 



Comments 



The ASSIGN or 
DEFINE command 
redirects the input stream 
from the command 
procedure file to the 
terminal. The /USER_ 
MODE qualifier specifies 
that the change remains 
in effect only while the 
next image is executing. 

Redirects output to the 
file you specify. 

Redirects the output 
stream to the file you 
specify while the next 
image is executing. 
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$! 
$! 

$! 
$! 



$! 
$! 
$! 



$ 

$ 

$ 

$! 

$! 

$! 

$! 

$ 

$! 

S! 

$! 

$ 

$ 

s 
$ 
$ 
$ 
$ 
$ 
$ 
s 
$ 



NOTICE.COM 



$! This command procedure creates a text file containing 



the message you specify, then mails it to DIST.DIS, 
a predefined distribution list. 



$! First, display instructions to the user. 
$! 

WRITE SYS$OUTPUT " " 

WRITE SYS$0UTPUT "Enter your message. Press CTRL/Z when done." 

WRITE SYS$0UTPUT " " 



Redirect the logical SYS$INPUT from the command 
procedure to the terminal. 

ASSIGN/USER_MODE SYS$C0MMAND SYS$ INPUT 

Have the user create the message. 

EDIT MESSAGE.TXT 

When the user exits the editor, the command procedure 
continues . 



Send the message. The lines following the MAIL 
command are data lines used by the MAIL utility. 
The dollar sign indicates the end of the data. 



MAIL 
SEND MESSAGE.TXT 
0DIST.DIS 

A NOTE FROM YODR SUPERVISOR 
S! 

S ! Leave the procedure 
$! 
$ EXIT 



Example 7-4 Using Terminal Input and Output 
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ULCS Uli JC*X*Wiipic / — m. 

1. The WRITE SYS$OUTPUT commands display the character string you specify 
on the terminal screen. 

2 The ASSIGN/USERJMODE SYS$COMMAM> SYS$INPUT command 
redefines the logical name SYS$INPUT to equate to SYS$COMMAND. This 
command redirects input from the command procedure file to the terminal. Because 
the /USER_MODE qualifier is used, this redirection stays in effect for only one 
command. In this example, it is the EDIT command. 

3. The EDIT MESSAGE.TXT command creates the file MESSAGE.TXT. The user's 
input on the terminal screen is placed in the file. When the message is completed, 
the user ends the command by pressing CTRL/Z. When the user presses CTRL/Z, 
control is passed back to the command procedure. 

4. The Mail utility is invoked using the Mail command SEND MESSAGE.TXT. 
The distribution list (DIST.DIS) should have been created prior to this for the 
command procedure to work. 

5. The lines following the MAIL command are data lines used by the Mail utility. 
Because they are data lines, they are not preceded by a dollar sign. When a 
procedure encounters a dollar sign, it automatically terminates the utility. 



7-22 WRITING COMMAND PROCEDURES 



7.8 DCL SYMBOLS 

Symbols are names to which you can assign a character string or an integer value. 
Symbols have two primary purposes. They can be used as command synonyms, or as 
variables in command procedures. For example, you can create a symbol HOME that 
has the value "SET DEFAULT SYS$LOGIN." HOME is a command synonym because 
it can be used synonymously with the command SET DEFAULT SYS$LOGIN. An 
example of a symbol as a variable might be assigning the symbol COUNT the integer 
value 1. 

Symbols are defined using assignment statements. There are two types of symbols 
available: local symbols and global symbols. Local symbols remain in effect only while 
the command procedure is executing. Global symbols remain in effect until the process 
terminates. 

Global symbols are often used to define command synonyms in your LOGIN.COM 
procedure. Global symbols defined in this way allow you to use synonyms in place of 
commands. When defined as global symbols, the definitions remain in effect as long as 
you are logged in. 

The use of symbols in command procedures provide possibilities not readily available at 
the interactive level. Using symbols as numeric and string variables expands the power 
and flexibility of DCL commands. 

Table 7-5 shows examples of assigning local and global symbol values. 
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Table 7-5 Symbol Assignment and Manipulation 



Operation 



Operator 



Assign an integer value to a 
local symbol 

Assign an integer value to a 
global symbol 

Assign a character string to a 
local symbol 



Example 



COUNT = 1 



NEWCOUNT ==100 



DSER = " SMITH'' 
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7.8.1 Symbol Substitution 

In a command procedure, symbols are frequently used as command synonyms, 
parameters, and as numeric and string variables. 

To be useful within a command procedure, the system must translate symbols into 
their corresponding values. Some DCL commands replace symbols with their values 
automatically. Most DCL commands do not perform automatic symbol substitution. 

You can tell the system to force symbol substitution. To indicate to the system that a 
symbol value should be substituted, enclose the symbol name in apostrophes ('). When 
the symbol name is contained in a character string, the symbol name must be preceded 
with two apostrophes (") and ended with a single apostrophe ('). 

Table 7-6 lists those commands and statements that perform automatic symbol 
substitution, as well as examples of nonautomatic substitution. 
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Table 7-6 Symbol Substitution Techniques 



Symbol Usage 



Command synonym 
(first item after $ 
prompt) 

In the right-hand 
side of an = or == 
assignment statement 

In an IF or WRITE 
command 

In a DCL command 
that does not perform 
automatic symbol 
substitution 

In a character string 



Concatenating two 
symbols in a DCL 
command that does 
not perform automatic 
symbol substitution 



Substitution 
Technique 



Automatic 



Automatic 



Automatic 



Surround the symbol 
with apostrophes (') 



Place two apostrophes 
in front of the symbol, 
and one apostrophe 
after it 

Surround each symbol 
with apostrophes (do 
not leave a space 
between the symbols) 



Example 



$ XX = "DELETE" 
$ XX FILE. TXT; 1 



S CODNT = COUNT + 1 

$ FILESPEC = NAME + " .TXT" 



$ IF COUNT .GT. 10 THEN 



$ RUN 'PROGRAM' 



$ WRITE SYS$OUTPUT - 

"The file "FILE' exists." 



$ PRINT 'NAME' 'TYPE' 



7-26 



WRITING COMMAND PROCEDURES 



$ 
$ 
$ 
$ 
$ 
$ 
$ 
$ 
$ 
$ 
$ 
$ 
$ 
$ 
$ ! 



REPORT3 . COM 

This command procedure sets your default directory to the 
[REPORTS. 'DAY'] subdirectory, prints out a report for the 
day of your choice, returns you to your login device and 
directory, then exits. 

Ask which daily report to print out 

INQUIRE DAY "Day to print a report" 

WRITE SYS$OUTPOT "" 

WRITE SYS$OUTPUT "Changing your default directory" 



$ ! Set your default to the correct subdirectory 

$ ! 

$ SET DEFAULT DISK1 : [REPORTS .' DAY' ] 

$ ! 

$ WRITE SYS$OUTPUT "" 

S WRITE SYS$OOTPUT "Printing the "day' report" 

$ ! 

$ ! Print out the report for the correct day 

$ ! 

S PRINT 'DAY' .RPT 

$ ! 

$ ! Return to your login device and directory 

$ ! 

S WRITE SYS$OUTPUT "" 

$ WRITE SYS$0UTPUT "Changing back to your login directory" 

$ SET DEFAULT SYS$LOGIN 
$ EXIT 

Execution ofREPORT3.COM: 

$ 0REPORT3 

Day to print report for: TUESDAY 

Changing your default directory 

Printing the TUESDAY report 

Job TUESDAY (queue SYS$PRINT, entry 47) started on WORK$TXA0 

Changing back to your login directory 



Example 7-5 Using Symbol Substitution 
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7.8.2 Passing Parameters to Command Procedures 

Parameters are the objects of DCL commands. A parameter might be a keyword, file 
specification, or an integer or string value. Since command procedures are made up 
of DCL commands, they frequently use parameters. You can specify parameters for a 
command procedure when you execute the procedure. 

The system automatically provides eight local symbols: PI - P8. You can pass up to 
eight numeric or string values to the procedure. If you specify parameters, the system 
assigns the values you specify to these symbols at execution time. If you do not specify 
a parameter, the default value assigned to the symbol (the null string) remains in effect 
The syntax is: 

$ @command_procedure.com parameterl parameter_2 ... parameter_8 
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$ 
$ 
$ 
$ 
$ 
$ 
$ 
$ 
$ 
$ 
$ ! 



REPORT4.COM 

This command procedure sets your default directory to the 
[REPORTS. 'PI' ] subdirectory, prints out a report for the day of 
your choice, returns you to your login device and directory, 
then exits . 

WRITE SYS$0UTP0T "" 

WRITE SYS$OUTPUT "Changing your default directory" 



$ ! Set your default to the correct subdirectory 

$ SET DEFAULT DISK1 : [REPORTS .' PI' ] 

$ ! 

$ WRITE SYS$OUTPUT "" 

$ WRITE SYS$OUTP0T "Printing the "PI' report" 

$ ! 

$ ! Print out the report for the correct day 

$ ! 

$ PRINT 'PI' .RPT 

$ ! 

$ ! Return to your login device and directory 

$ ! 

$ WRITE SYS$00TPUT "" 

$ WRITE SYS$OUTPUT "Changing back to your login directory" 

$ ! 

$ SET DEFAULT SYS$L0GIN 

$ EXIT 

Execution of REPORT4.COM 

$ SREP0RT4 TUESDAY 

Changing your default directory 

Printing the TUESDAY report 

Job TUESDAY (queue SYS$PRINT, entry 47) started on WORK$TXA0 

Changing back to your login directory 



Example 7-6 Passing Parameters to Commands Procedures 
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7.9 CONTROLLING PROGRAM rjuOW 

The normal order of command execution in a procedure is sequential. That is, the 
first line of the procedure executes, then the second, and so on. This sequential order 
is sufficient in some procedures, such as a LOGIN.COM file, which usually performs 
unconditional tasks. 

There are times, however, when you will want to alter the order of execution, depending 
on the results of conditional testing within the procedure. For example, you may want 
a file to print, but only if it has the proper file type. DCL provides several commands 
that allow you to alter the order of execution. These control-flow commands include 
the IF command, and the GOTO command. 



7.9.1 The IF Command 

Syntax: 

$ IF conditional expression THEN command 

When the command executes, the conditional expression following IF is tested. This 
conditional expression may to compare integer values, compare two string expressions, 
or test whether or not a logical expression is true or false. Table 7-7 lists the operators 
used in conditional expressions. 

If the condition is met, the command(s) following THEN are performed. 

If the condition following IF is not met, then the next DCL command in sequence 
is performed, or an optional ELSE statement can be performed. The optional ELSE 
statement provides command(s) to be performed when the IF condition is false. 

The command(s) following THEN or ELSE can be: 

Another DCL command(s), or 
A GOTO command 

The syntax of the IF-THEN-ELSE command is: 

$ IF conditional expression THEN command ELSE command(s) 



7 ~ 30 WRITING COMMAND PROCEDURES 



7.9.2 Notes on the DF-THEN-ELSE Command 

A command block started by a THEN statement must be terminated by an ENDIF 
statement 

A THEN statement must be the first executable statement following an IF 
statement. 

THEN, ELSE, and ENDIF statements cannot be abbreviated to fewer than four 
characters. 

Do NOT specify labels on a THEN or ELSE statement. 

Labels are legal only on an ENDIF statement. 

Command procedures may branch within the current command block, but branching 
into the middle of another command block is not recommended. 

7.9.3 The GOTO Command 
Syntax: 

$ GOTO label 

The GOTO command does not perform any conditional testing. Rather, control is 
transferred to the label that follows the GOTO command. The DCL command that 
follows the label is then performed. This label can occur either before or after the 
GOTO command. 
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Table 7-7 Relational Operators Used in Expressions 



Operator 



Description 



String Operators 

.EQS. 

.GES. 

.GTS. 

.LES. 

.LTS. 

.NES. 

Numeric Operators 

EQ. 

.GE. 

.GT. 

.LE. 

.LT. 

.NE. 

Logical Operators 

.NOT. 
.AND. 
.OR. 



Tests if two character strings are equal. 

Tests if the first string is greater than or equal to the 

second string. 

Tests if the first string is greater than the second 
string. 

Tests if the first string is less than or equal to the 
second string. 

Tests if the first string is less than the second string. 

Tests if the two strings are not equal. 



Tests if two numbers are equal. 

Tests if the first number is greater than or equal to 
the second number. 

Tests if the first number is greater than the second 
number. 

Tests if the first number is less than or equal to the 
second number. 

Tests if the first number is less than the second 
number. 

Tests if two numbers are not equal. 



Logically negates a number. 

Combines two numbers with a logical AND. 

Combines two numbers with a logical OR. 
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$ 
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$! 
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$! 
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$! 

$! 
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$! 

$ 

S! 

$ 

$ 

$! 

$ 

$ 



DEL DIR.COM 



This command procedure deletes previously emptied 
directories . It assumes that the directory to be 
deleted is owned by the procedure's user. 

Check to see if the user entered the directory name . 

If yes, skip to the confirmation question. 

If no, display a message and ask for the directory name 

IF PI .NES. "" THEN GOTO CONFIRM 

WRITE SYS$0UTP0T " " 

WRITE SYS$OUTPDT "This procedure deletes an emptied directory" 

WRITE SYS$OUTPDT "The .DIR file extension is assumed." 

WRITE SYS$OUTPUT " " 

INQUIRE PI "Directory name" 

CONFIRM: 

INQUIRE P2 "Confirm, please (Y/N) " 

If the user answers 'No', abandon this procedure. 

IF .NOT. P2 THEN GOTO NODELETE 

Reset the directory protection so that the owner 
can delete it, delete the directory and display 
the system message. Note that the procedure 
substitutes the directory name for the symbol PI . 

SET PROTECTION=(0:RWED) 'PI'. DIR;* 
DELETE/LOG 'PI'. DIR;* 
GOTO END 

NODELETE : 

WRITE SYS$OUTPUT " " 

WRITE SYS$OUTPUT "Directory file not deleted." 

END: 
EXIT 



Example 7-7 Controlling Program Flow in a Command Procedure 
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.Execution of DEL_Djlk.COM: 



$ @DEL_DIR TEST 

Confirm, please (Y/N) : Y 

%DELETE-I-FILDEL, DISK: [DENISE] TEST .DIR; 1 deleted (3 blocks) 

$ 



Second execution: 



$ @DEL_DIR 

This procedure deletes an emptied directory 
The .DIR file extension is assumed. 

Directory name: TEST2 

Confirm, please (Y/N) : Y 

%DELETE-I-FILDEL, DISK: [DENISE] TEST2 .DIR; 1 deleted (3 blocks) 

$ 

Third execution: 



$ @DEL_DIR 

This procedure deletes an emptied directory 
The .DIR file extension is assumed. 

Directory name: TEST3 
Confirm, please (Y/N) : N 

Directory file not deleted. 
$ 

Example 7-7(Cont.) Controlling Program Flow in a Command Procedure 
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7.10 LEXICAL FUNCTIONS 

Lexical functions are features of the DCL command language that provide information 
similar to that of some DCL commands. The primary difference between DCL 
commands and lexical functions is the manner in which the information is provided. 

In most instances, the information provided by a DCL command is returned to the 
terminal. Although well suited for display, it is not easily manipulated or changed. For 
example, the SHOW TIME command displays the current time on the terminal like 
this: 

$ SHOW TIME 
18-JUN-1988 10:10:89 

$ 

There is no simple method to use this information in a command procedure. On the 
other hand, information provided by a lexical function is returned as a symbol value. 
This symbol and its associated value can be used in a command procedure. For example, 
you can assign the current date and time to a symbol, like this: 

$ TIME = F$TIME() 

You can now use the symbol TTME in subsequent DCL commands within the procedure. 

All lexical functions return a value. This value can be an integer or a character string, 
depending on the lexical function. For complete information on the syntax, parameters, 
and use of lexical functions, refer to the VMS DCL Dictionary. 
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S 

$ 



INFO . COM 



This command procedure allows the user to leave a message 
on the terminal screen, along with information about the 
process. The time when the message was left is also displayed. 



Use lexical functions to determine the current time 

and day of the week 

TIME = F$TIME() 

CURR_TIME = F$EXTRACT(12,5,TIME) 

WEEKDAY = F$CVTIME (TIME, , "WEEKDAY") ! Returns Monday, Tuesday, etc. 

Clear the screen using the TYPE/PAGE NL: command 
TYPE/PAGE NL: 

Display process name, the time, and the day of the week. 

NAME= F$PROCESS() 

WRITE SYS$OUTPUT NAME 

WRITE SYS$OUTPUT " " 

WRITE SYS$ODTPUT "IT IS " CURR_TIME' ON A "WEEKDAY"' 

WRITE SYS$OUTPDT " " 

Leave the procedure 

END: 
EXIT 



Execution of INFO.COM 

$ 8INF0 
DENISE 

IT IS 12:23 ON A Monday 



Example 7-8 Using Lexical Functions 
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All lexical functions begin with F$, followed by the function name. 

WHO = F$PROCESS() 

All lexical functions require parentheses, even with null arguments. 
Multiple arguments are separated by commas. 
Optional arguments, when omitted, are indicated by commas. 
Examples of arguments supplied to lexical functions: 

• Integer or character strings 

WHAT = F$EXTRACT (0,3, "MAILMAN" ) 

• Symbols 

HOWLONG = F$LENGTH (PI) 

• Keywords 

WHERE = F$ENVIRONMENT ("MESSAGE") 

• Null arguments 

WHEN = F$TIME ( ) 



WRITING COMMAND PROCEDURES 



7-37 



labie 7-8 Frequently Used Lexical Functions 



Lexical Function 



Description 



F$TIME() 

F$PROCESS() 
F$MODE() 



F$LENGTH(string) 
F$LOCATE(substring,string) 

F$EXTRACT(offset,ninnber,string) 

F$CVTIME([input-tiine] .[format] - [field]) 

F$ENVIRONMENT(item) 
F$GETQUI() 

F$LOGICAL(logical-name) 



Returns the current date and time 
string. 

Returns the current process name. 

Returns a character string 
indicating the mode in 
which a process is r unning 
(INTERACTIVE, NETWORK, or 
OTHER). 

Returns the length of a string. 

Locates the substring in the string 
and returns the offset position. 

Extracts a substring from a 
character string expression. 

Returns information about 
absolute, combination, or delta 
time strings. 

Returns information about the 
DCL command environment. 

Returns information regarding 
queues and the batch and print 
jobs currently in those queues. 

Returns the equivalence string 
associated with the logical 
name. Does not perform iterative 
translation automatically. 
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PRINT . COM 

This procedure allows you to print multiple copies 
of any file you choose. It will ask for the file 
name and number of copies if the information is 
not supplied on the command line. The procedure 
will not let the user print a binary file. 

NAME_FILE: 

IF PI .EQS. "" THEN INQUIRE PI "File to be printed" 

LENGTH=F$LENGTH (PI) 

IF LENGTH .EQ. THEN GOTO NAME_FILE 

PERIOD=F$LOCATE ( " . " , P 1 ) 
FNAME=F$EXTRACT ( , PERIOD , P 1 ) 

! Check to see if user entered file type. If yes, separate 

! filename from file type. If no, assign .LIS type to the file 

i 

IF LENGTH .EQ. PERIOD 

THEN FTYPE=".LIS" 
ELSE FTYPE=F$EXTRACT (PERIOD, LENGTH-PERIOD , P 1 ) 
END IF 

Check to see if user entered a binary file type. If yes, exit. 
If no, see how many copies they want. 



IF FTYPE .EQS. ".OBJ" .OR. FTYPE .EQS. ".EXE" 

THEN WRITE SYS$OUTPUT "YOU CANNOT PRINT A 
EXIT 

END IF 



'FTYPE' FILE" 



NOMBER_COPIES: 

IF P2 .EQS. "" THEN INQUIRE/NOPUNCTUATION P2 "HOW MANY COPIES DO Y00 WANT? " 

IF NUMBER .LE. THEN GOTO NUMBER_COPIES 

! Print the correct number of copies then exit from the procedure 
! 

PRINT/COP IES='P2' 'FNAME"FTYPE' 

EXIT 



Example 7-9 Using More Detailed Lexical Functions 
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Notes on Example 7-9: 

1 $ LENGTH = F$LENGTH (PI) 

The F$LENGTH lexical function returns the length of the character string in the 
local symbol PI and assigns this value to the symbol LENGTH. 

2 $ IF LENGTH .EQ. THEN GOTO NAMEJFILE 

If this statement is true, then the command procedure returns to the label 
NAMEFTLE on the premise that the user did not type in a file name. 

3 $ PERIOD = F$LOCATE ( " . " , P 1 ) 

The F$LOCATE lexical function locates the period in the local symbol PI and 
returns its offset within the string to the symbol PERIOD. 

4 $ FNAME = F$EXTRACT(0, PERIOD, PI) 

The FSEXTRACT lexical function extracts the file name (substring) by starting at 
the offset position (0) up to PERIOD in PI and assigns it to the symbol FNAME. 

The lexical function IF-THEN-ELSE is employed here: 

5 $ IF LENGTH .EQ. PERIOD 
$ THEN FTYPE = ".LIS" 

If the symbol LENGTH and the symbol PERIOD hold the same value, they 
automatically assign the symbol FTYPE or .LIS to the file. 

6 $ ELSE FTYPE = F$EXTRACT (PERIOD, LENGTH-PERIOD, PI) 

If a "." was found in the PI string, we assume a file type was specified. Extract 
the file type from PI. 



WRITING COMMAND PROCEDURES 7-41 



7.11 SUMMARY 



A command procedure is a file containing DCL command strings 
These command strings are made up of: 

— DCL command verbs 

— Command parameters 

— Qualifiers 

Command procedures frequently make use of: 

— DCL symbols - command synonyms, numeric and string variables 

— Control flow commands - IF, GOTO 

— Lexical functions 

You can perform terminal input and output functions using: 

— INQUIRE 

— READ SYSSCOMMAND 

— WRITE SYS$OUTPUT 

— TYPE SYS$INPUT 

Control flow commands allow you to alter the order of command execution 

— IF-THEN or IF-THEN-ELSE - transfers control based on the results of 
conditional expressions 

— GOTO - unconditionally transfers control 

You can pass numeric and string information to the command procedure using the 
local symbols PI - P8 associated with every command procedure 

Lexical functions allow you to gather and use system and process information in 
command procedures 
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7.12 WRi 1 1 cN EXc-RCISE I 

To complete these exercises, use the following symbol definitions: 



COUNT = 2 


FILE NAME = "PROGRAM" 


PI = "MYFILE.TXT" 


FILE TYPE = ".FOR" 


P2 = "DATA. DAT" 





Part A: 

Each command below uses a symbol in some way. Indicate whether or not the symbol 
is used correcdy. If it is used correcdy, rewrite the command, replacing the symbol with 
its value (see above). If the symbol is used incorrectly, rewrite the command correcdy. 

Examples: 

$ TYPE "PI" 

Incorrect: $ TYPE 'PI' 

$ EDIT 'P2' 

Correct: $ EDIT DATA.DAT 



1. $ FILE = 'FILE_NAME' + 'FILEJTYPE' 

2. $ WRITE SYS$OUTPUT COUNT " copies of the file" 

3. $ IF COUNT XT. 10 THEN GOTO END 

4. $ WRITE SYS$OUTPUT "The file "FILE_NAME'"FILE_TYPE' 
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PartB: 

For the commands below, replace the underlined text with symbols, using the proper 
symbol substitution techniques. Use the same symbol values you used in Part A. 

Example: 

$ PRINT MYFILE.TXT 

$ PRINT 'PI' 



1. $ WRITE SYS$OUTPUT "The file is MYFILE.TXT " 

2. $ TYPE PROGRAM.FOR 

3. $ EDIT DATA.DAT 

4. $ WRITE SYS$OUTPUT "2 copies of the file DATA.DAT exist." 

5. $ FILE = "PROGRAM" + ".FOR" 
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7.13 INTRODUCTION TO LABORATORY EXERCISES 

These lab exercises are designed to give you practice in creating, testing, and running 
command procedures. 

The procedures in these exercises include the commonly used functions of command 
procedures, such as: 

Terminal input and output 

Symbol assignment and symbol substitution 

Controlling program flow 

Passing data to procedures 

Using simple lexical functions 
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7.14 LABORATORY EXERCISE I 

LOGIN.COM is one of the most commonly used command procedures. This procedure 
is executed automatically each time you log in to a VMS system. It is used to tailor 
your working environment on the system to better suit your needs. 

Write a L0GIN.COM of your own that performs the following actions: 

1. Exits if the process mode is not interactive. Use the lexical function F$MODE() 
to test the mode of the process. 

2. Defines a logical name that points to one of your subdirectories: 

disk_name : [ directory_name . subdirectory_name ] 

where disk_name is your default disk, and directoryjname is your top-level 
directory. 

3. Defines global symbols to be used as command synonyms. The command 
synonyms, when defined should perform the following actions: 

Set default 

• Show all users currently logged in to the system 
Display your current directory 

• Set your default to your login disk and directory 

4. Displays the following information on your terminal: 

The current date and time 

• The current default directory 
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7. 15 LABORATORY EXERCISE H 

Write a command procedure that allows you to create files that everyone on your system 
can access. The procedure should perform the following tasks: 

1. Asks for the file name if it is not provided. 

2. Displays a message that indicates the name of the file being edited. 

3. Transfers control to the terminal and then allows you to edit the file. 

4. Sets the protection on the file so that the WORLD has READ access. 

5. Prints a copy of the file for yourself, if you choose. 

The name of the file you are creating should be supplied as PI. 

This exercise uses terminal input and output including: 

INQUIRE 

WRITE SYS$OUTPUT 

DEFTNE/USER_MODE or ASSIGN/USER_MODE 
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7.16 LABORATORY EXERCISE HI 

The sample file ADD.COM, shown below, is intended to request two numbers, add 
them together, and display their sum. It doesn't behave as expected. 



$ 



ADD . COM 



Adds two numbers together and displays their sum. 
(This command procedure doesn't work as expected.) 



$ 

$ 

$ 

$WRITE SYSSOOTPUT "This command procedure will add two numbers together 

$ INQUIRE PI "FIRST VALUE" 

$ INQUIRE P2 "SECOND VALUE" 

$T0T = PI + P2 

$WRITE SYS$0UTPUT "TOTAL IS ", TOT 

Invoke ADD.COM, supply the input it requests, and determine what is wrong with it. 
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7.17 LABORATORY EXERCISE IV 

The sample file SAVDIR.COM is shown below: 



$ i SAVDIR.COM 

$! Save current default directory, set default to a 

$! new directory specified by the user, demonstrate 

$! the new default, then reset to the original default. 

$! This generates errors - can you fix it? 

$ 

$CURDIR==F$DIRECTORY () 

$WRITE SYS$OUTPUT "CURRENT DIRECTORY IS ",CORDIR 

$INQDIRE NEWDIR "ENTER NEW DIRECTORY SPECIFICATION" 

$SET DEFAULT NEWDIR 

$DIRECTORY 

$SET DEFAULT CURDIR 

$DIRECTORY 

SAVDIR.COM is intended to do the following: 

Determine and display the user's current default directory 

Request a new directory specification from the user 

Set default to that new directory 

Generate a $DIRECTORY listing to demonstrate the new default 

Set the default back to the original directory 

It generates an error and does not behave as expected. 

Invoke SAVDIR.COM, supply the input it requests, interpret the resulting error message, 
and determine what is wrong with the procedure. 
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7. 1 8 LABORATORY EXERCISE V 

The sample files IF_THEN_1.COM and EF_THEN_2.COM, shown below, are intended 
to request a number from the user and determine whether it is odd or even. They do 
not work properly. 



$ ! IF-THEN_1 . COM 

$ ! Decide whether a number is odd or even . 

$ ! This generates errors - can you fix if 

$ 

$ INQUIRE X "TYPE A NUMBER" 

$ IF X THEN WRITE SYS$OUTPUT "ODD" 

$ ELSE WRITE SYS$0UTPUT "EVEN" 

$ ENDIF 

$ WRITE SYS$OUTPUT "DONE" 



$ ! IF-THEN_2 . COM 

$! Decide whether a number is odd or even. 

$! This doesn't work when an odd number is given - 

S ! can you fix it? 

$ 

$ INQUIRE X "TYPE A NUMBER" 

$ IF X 

$ THEN WRITE SYS$0UTPUT "ODD" 

S ELSE WRITE SYS$OUTPUT "EVEN" 

$ WRITE SYS$OUTPUT "DONE" 

Invoke each command procedure, supply both odd and even values, and determine what 
is wrong with the procedures. 
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7,19 OPTIONAL LABORATORY EXERCISE 

Write a command procedure that displays a message on your terminal screen that states 
when you will return. The procedure should perform the following tasks: 

1. Asks you for the number of minutes you will be away. 

2. Erases the screen and then displays the following message, 12 lines from the top: 

"Back in N minutes" 

(where N is the number of minutes you supplied in Part 1). 

3. It waits, and at one-minute intervals subtracts 1 from the number of minutes, 
erases the screen and redisplays the message with the new value. 

4. When only one minute is left, it erases the screen and displays the message: 

"I'll be right back." 
This exercise uses terminal input and output commands, including: 
INQUIRE/NOPUNCTUATION 
WRITE SYS$OUTPUT 
TYPE SYS$INPUT 

This procedure also uses the DCL command WATT. For more information on this 
command, refer to the VMS DCL Dictionary. 

This procedure does NOT use lexical functions. 
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Part A: 

Each command below uses a symbol in some way. Indicate whether or not the symbol 
is used correctly. If it is used correctly, rewrite the command, replacing the symbol with 
its value. If the symbol is used incorrectly, rewrite the command correctly. 

1. $ FILE = 'FILE_NAME' + 'FELEJTYPE' 

Incorrect Correct command is: $ FILE = FILE_NAME + FELEJTYPE 

Do not use symbol substitution characters on the right-hand side of an = assignment 
statement 

2. $ WRITE SYS$OUTPUT COUNT " copies of the file" 

Incorrect Correct command is: $ WRITE SYS$OUTPUT COUNT, " copies of 
the file" 

Separate the items in the output list with commas. The values will be concatenated. 
Note that the symbol COUNT is substituted automatically. 

An alternate method: $ WRITE SYS$OUTPUT '"'COUNT' copies of the file" 

If you place the symbol COUNT within the quoted string, symbol substitution 
does not occur automatically. For symbol substitution to occur, precede the symbol 
with two apostrophes. 

3. $ EF COUNT .LT. 10 THEN GOTO END 
Correct $ IF 2 .LT. 10 THEN GOTO END 

DCL automatically performs symbol substitution in an IF command. 

4. $ WRITE SYS$OUTPUT "The file "FILE_NAME , "FILE_TYPE'" 

Correct $ WRITE SYS$OUTPUT "The file PROGRAM.FOR" 

In a character string, a symbol must be preceded by two apostrophes and followed 
by one. 
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PartB: 

In the commands below, replace the underlined text with symbols, using the proper 
symbol substitution techniques. Use the same symbol values you used in Part A. 

1 . $ WRITE S YS$OUTPUT "The file is MYFTT .F..TXT " 
$ WRITE SYS$OUTPUT "The file is "PI"' 

2. $ TYPE PROGRAM.FOR 

$ TYPE 'FILE_NAME"FILE_TYPE' 

3. $ EDIT DATA.DAT 
$ EDIT 'P2' 

4. $ WRITE SYS$OUTPUT "2 copies of the file DATA.DAT exist." 

$ WRITE SYS$OUTPUT ""COUNT' copies of the file "P2' exist." 

5. $ FILE = "PROGRAM" + ".FOR" 

$ FILE = FILE_NAME + F1LE_TYPE 
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$ I LOGIN . COM 

$! 

$! 

$! Check to see if process is interactive. If not, exit 

$! 

$ IF F$MODE() .NES. "INTERACTIVE" THEN EXIT 

$! 

$ ! Define a logical name that points to the 

$ ! COMPROC subdirectory . 

$! 

$ DEFINE COMPROC DISK1: [MANN .COMPROC] 

$! 

$! Alternately, use ASSIGN DISK1 : [MANN. COMPROC] COMPROC 

$! 

$! Create global symbols to be used as command synonyms 

$! 

$ SED == "SET DEFAULT" 

$ WHO == "SHOW USERS" 

$ SHD == "SHOW DEFAULT" 

$ HOME = "SET DEFAULT SYS$LOGIN" 

$! 

$! Display some "time and place" information on the terminal 

$! 

$ SHOW TIME 

$! 

$ SHOW DEFAULT 

$! 

$! Leave the procedure in an orderly manner. 

$! 

$ EXIT 



Resets default 
Displays all users 
Displays current directory 
Resets default to login values 
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7.22 LABORATORY EXERCISE H— SOLUTION 

$! CREATE FILE.COM 

$1 

S! 

$! Expected parameters: PI = name of file to be edited 

S! 

$! This command procedure allows you to edit a file, sets the 

$ ! protection on the file so that the World has READ access, 

S ! then gives you the option of printing a copy of it . 

$! 

$! Be sure the name of the file is assigned to PI. If not, ask: 

$! 

$ IF PI .EQS. "" THEN INQUIRE PI "Filename" 

$! 

$! Display a message that indicates what file is beinq created: 

$! 

$ WRITE SYS$OUTPUT " " 

$ WRITE SYS$0UTP0T "Editing the file "PI'..." 

$ WRITE SYS$0UTP0T " " 

$! 

$! Redirect SYS$INPUT so that it points to the terminal: 

$! 

$ DEFINE/DSER_MODE SYS$INPUT SYS$COMMAND 

$! 

$! Alternately, ASSIGN/DSER MODE SYS$COMMAND SYS$INPUT 

$! 

$'. Allow the user to edit the file: 

S! 

$ EDIT 'PI' 

$! 

$! Set the required protection for the file: 

$! 

$ SET PROTECTION (W:R) 'PI' 

$! 

$! Present the option of printing the file: 

$! 

$ INQDIRE/NOPUNCTUATION ANS "Print a copy of the file? " 

$ IF ANS THEN PRINT 'PI' 

$ EXIT 
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7,23 LABORATORY EXERCISE HI— SOLUTION 

^ , ADD_SOL . COM 

g j Corrects the error in ADD.COM 

$ 

$WRITE SYS$OUTPUT "This command procedure will add two numbers together . " 

$ INQUIRE PI "FIRST VALUE" 

$INQUIRE P2 "SECOND VALUE" 

$TOT = + PI + P2 • Note the correction here. 

$WRITE SYS$OUTPUT "TOTAL IS ", TOT 

$ 

$! PI and P2 are assumed to be strings, so DCL concatenates them. 

$! Force DCL to regard them as numeric symbols by preceding them with a 

$! number. Zero makes sense because it won't change the value of the sum. 
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7.24 LABORATORY EXERCISE IV— SOLUTION 

$ ! SAVD IR_SOL . COM 

$! This corrects the errors in SAVDIR.COM. 

$ 

$CURDIR==F$DIRECTORY (} 

$WRITE SYS$OUTPUT "CURRENT DIRECTORY IS ",CURDIR 

$INQUIRE NEWDIR "ENTER NEW DIRECTORY SPECIFICATION" 

$SET DEFAULT 'NEWDIR' . Note correction here 

$DIRECTORY 

$SET DEFAULT 'CURDIR' I and here. 

SDIRECTORY 

$ 

$! The original SAVDIR.COM did not have apostrophes around 

$! the symbols NEWDIR and CURDIR, so the SET DEFAULT commands 

$ ! assumed that they were logical names . 

$! Use apostrophes to force symbol substitution in a situation 

$ ! where symbols are not expected. 
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7.25 LABORATORY EXERCISE V— SOLUTION 



5 I IF-THEN_l_SOL . COM 

$! This corrects the error in IF_THEN_1.COM 

$ 

$ INQUIRE X "TYPE A NUMBER" 

$ IF X ! Note the correction here. 

$ THEN WRITE SYS$OUTPUT "ODD" 

$ ELSE WRITE SYS$OUTPUT "EVEN" 

$ END IF 

$ WRITE SYSSOUTPUT "DONE" 

$ 

$! if you use ELSE, THEN should not be on the same line as IF. 

$ i You are mixing constructs . 
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$! IF-THEN_2_SOL.COM 

S ! Decide whether a number is odd or even . 

S! This doesn't work when an odd number is given - 

$! can you fix it? 

$ 

$ ! INQUIRE X "TYPE A NUMBER" 

$! IF X 

$! THEN WRITE SYS$0UTP0T "ODD" 

$ ! ELSE WRITE SYS$00TPUT "EVEN" 

$! WRITE SYS$ODTPDT "DONE" 

$! 

$! This works fine with even input because the ELSE condition is met, 

'•' so we skip over the statement (s) associated with THEN and just fall 



$! 

$ ! through . 



$! 

$! The trouble comes when odd input is supplied. 

$! Since the THEN condition (truth for the IF test) is met, we execute 

$! the indicated statements and try to skip over the statements for ELSE. 

$ ! But where do we go when there's no ENDIF to finish up the IF-THEN? 

S 

$ 

$! IF_THEN_2_S0L.COM - Corrected procedure 

S 

$ INQUIRE X "TYPE A NUMBER" 

$ IF X 

$ THEN WRITE SYS$OUTPUT "ODD" 

$ ELSE WRITE SYS$OUTPUT "EVEN" 

$ ENDIF ! Here is the correction 

$ WRITE SYS$OUTPUT "DONE" 
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7.26 OPTIONAL LABORATORY EXERCIS&— SOLUTION 



$ i BACK_SOON.COM 

$ ! . 

$ ! This command procedure asks the user how many minutes he/she will 

$ ! be away. It erases the screen and displays the message "Back in 

$ ! 'n' minutes". It waits a minute, recalculates the value of N, and 

$ ! redisplays the message. When only one minute is left, it displays 

$ ! "I will be right back". 

$ ! 

$ ! Inquire for the number of minutes the user intends to be away. 

$ WHEN: 

$ INQDIRE/NOPUNCTUATION BACKSOON "How many minutes? " 

$ ! 

$ ! If no answer, ask again. 

$ IF BACKSOON .EQS. "" THEN GOTO WHEN 

$ ! 

$ ! Top of time loop 

$ LOOP: 

$ IF BACKSOON .EQ. 1 THEN GOTO RIGHTBACK 

$ ! 

$ ! Erase the screen 

$ SET TERMINAL/WIDTH=80 

S ! 

$ ! Use the TYPE SYS$INPUT command to type eleven blank lines on 

$ ! the terminal. 



$ TYPE SYS$INPUT 
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S ! Now use the WRITE SYS$OUTPUT command to display 

S ! the message on the screen. 

$ ! 

$ WRITE SYS$OUTPUT " Back in "BACKSOON' minutes' 

$ ! 

$ ! Wait one minute- -note that the terminal is 

$ ! tied up with this procedure. 

$ WAIT 00:01:00.00 

$ ! 

$ ! Subtract 1 from the number of minutes 

$ BACKSOON=BACKSOON - 1 

$ ! 

$ ! Loop until only one minute is left. 

$ GOTO LOOP 

$ ! 

$ ! The last step 

$ RIGHTBACK: 

$ ! 

$ ! Erase the Screen 

$ TYPE/PAGE NL: 

$ ! 

$ ! Use the TYPE SYSS INPUT command to type 

$ ! the necessary blank lines. 

$ TYPE SYS$ INPUT 



$ ! 

$ WRITE SYS$OUTPUT " I will be right back. 



$ END 
$ EXIT 
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8.1 INTRODUCTION 

In addition to your default disk device, which stores the files you and many other users 
catalogue hi your default directory hierarchies, your system includes a number of tape 
devices and smaller disk units. You can use one of these devices whenever you want to 
store copies of files on a private volume. Private volumes can be created on a magnetic 
tape reel, a floppy disk, or a smaller disk volume, such as an RK07 or RL02 pack. Once 
you copy files to such a volume, you can remove it and store it in some other secure 
location. 

This module introduces the steps and commands required to create, use, and protect a 
private volume. 

8.2 OBJECTIVES 

In order to use private volumes to store private files off-line and transport them from 
one system to another, you should be able to perform the following operations: 

Allocate, initialize, and mount volumes 

• Use the Backup Utility 

• Dismount and deallocate volumes 



8.3 RESOURCES 

To complete this module, you should have access to the following documents: 

VMS DCL Dictionary 
VMS Mount Utility Manual 
VMS Backup Utility Manual 
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8.4 CREATING AND USijnu PRIVATE VOLUMES 
8.4.1 The Uses of Private Disk and Tape Volumes 

Private disk and tape volumes are volumes that you own exclusively. They have three 
major uses: 

• To preserve files 

To transfer files from one system to another 
To provide a private environment for your work 

8.4.1.1 Preserving Files 

Your default disk, which you share with other system users, stores most of your files. 
This device is called a public disk. 

Although the protection you establish for your files is normally sufficient to guard 
them against inadvertent destruction, they are still vulnerable to the activities of more 
privileged users and the operating system. For this reason, most users make copies of 
their most important material on backup volumes, such as magnetic tape reels or disk 
packs. A volume you own is called a private volume. A private volume has an owner 
user identification code (UIC) identical to your own. 

8.4.1.2 Transferring Files 

You may find it necessary to transfer files between systems not connected by a 
communications link. In such circumstances, you must be able to move your files 
physically from one location to another. You can conveniently do this by copying your 
files to a portable volume, such as a tape reel or disk pack, and then carrying that 
volume to the other system. 
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8.4.1.3 Providing a Private Environment 

In certain circumstances, you may want to work on a device to which no one else has 
access. By creating a private volume and mounting it on a device assigned exclusively 
to your process, you can work without interference from other users. 

In creating and using private volumes, you will use a number of VMS commands. 
These commands allow you to prepare and gain access to a wide range of peripheral 
storage devices, as Figure 8-1 suggests. 
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$ volume manipulation command 



INTERACTIVE 
TERMINAL 



I VMS I 

COMMAND ■ 

LANGUAGE ■ 

INTERPRETER ■ 



MAGNETIC 
TAPE 





DECtape 



DISK 
PACK 



TTB^X0336_88_S 



Figure 8-1 Volume Manipulation Commands 
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8.4.2 Creating Private Volumes: The Command Sequence 

To create and use a private tape or disk volume, complete the following steps: 

1. Allocate a device. This reserves a device for exclusive use by your process until 
you deallocate it. 

2. Place a volume on the allocated device and load it. (Loading the volume physically 
prepares it to be accessed by commands issued to the device.) 

3. Initialize the volume if it is new, or if another user has discarded it. The process 
of initialization builds an appropriate file structure and establishes the ownership 
and protection of the volume. 

4. Issue the MOUNT command to make the volume accessible to your process. 
You can now create and manipulate files on the volume. You can also access the 
volume using a logical name. 

5. When you have completed your work with the volume, issue the DISMOUNT 
command. The dismount process prohibits further access to the volume until it is 
remounted. 

6. Unload and remove the volume from the device. 

7. Deallocate the device to make it available to other users. 

Table 8-1 lists the VMS commands to perform the above operations. 

Example 8-1 illustrates the use of these commands to prepare a private disk volume. 
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Table 8-1 Commands for Creating and Accessing Private Disk and Tape Volumes 



Operation 



Format/Example 



Comments 



Allocating a Device $ ALLOCATE device [logical-name] 



S ALLOCATE DM DISK 



Finds the first available 
RK06/RK07 and assigns it 
to your process. The logical 
name DISK is placed in 
your process logical name 
table and is assigned the 
name of the allocated device. 
Other users are unable to 
access the device. When 
the ALLOCATE command 
is used, the DISMOUNT 
command does not free the 
device for other users. 



Creating a file 
structure on a tape 
or disk 



$ INITIALIZE device label 



Builds the appropriate disk 
structure on the volume. 
Establishes volume ownership 
and protection. Usually used 
for new volumes. 



$ INITIALIZE DMA2: TESTDISK 



$ INITIALIZE MOAO: TSTTAP 



The disk volume mounted 
on DMA2: is labeled 
TESTDISK. You are declared 
owner of the disk. All user 
groups are allowed all types 
of access (RWED). You must 
own the disk or possess 
VOLPRO privilege. 

Builds ANSI level 3 tape 
structure on the volume 
located on device MUAO:. 
The volume receives the label 
TSTTAP. By default, you are 
declared the owner. All user 
groups are allowed all types 
of access (RWED). 
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Table 8-1 (Cont.) Commands for Creating and Accessing Private Disk and Tape Volumes 



Operation 



Format/Example 



Comments 



Creating a link 
between the volume 
and your process 



Creating a link 
between your 
process and a 
tape device, and 
specifying the 
volume to be 
placed on that 
device 



$ MOUNT device label [logical-name] 



$ MOUNT DMA2: TESTDISK DISK 



Mounts TESTDISK on the 
device DMA2:. The logical 
name DISK is assigned the 
equivalence name of DMA2. 



$ MOUNT device-name volume-label logical-name 



$ MOUNT MT: XFILES TAPE 



Issuing the MOUNT 
command with a generic 
device disk specification 
causes the system to select 
an available device of the 
specified type for your 
process. Once this command 
is issued, someone must 
mount the volume or you 
must issue the CTRL/C 
sequence to cancel the 
request. 
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Table 8-1 (Cent.) Commands for Creating and Accessing Private Disk and Tape Volumes 



Operation 



Format/Example 



Comments 



Breaking the link 
between the volume 
and your process 



$ DISMOUNT[/NOUNLOAD] device 



If you want to keep the 
disk online when you 
dismount it, use the qualifier 
/NOUNLOAD. 



$ DISMOUNT DMA2: 



Dismounts and automatically 
unloads the volume on 
DMA2:. Deletes the logical 
name assignment made by the 
MOUNT command. Unless 
the ALLOCATE command 
was used before the MOUNT 
command, this makes the 
device available to other 
users. 



Deallocating a 
device 



$ DEALLOCATE device 

$ DEALLOCATE DMA2 : 



Deallocates device DMA2:. 
Frees the device for use by 
other users. Does not delete a 
logical name assigned by the 
ALLOCATE command. 
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1 $ SHOW DEVICE DM: 



Device 


Device 


Error 


Volume 


Free 


Trans 


Mnt 


Name 


Status 


Count 


Label 


Blocks 


Count 


Cnt 


DMAO : 


Online 













$ ALLOCATE DM: 


DISK 













%DCL-I-ALLOC, DMAO: allocated 

3 $ MOUNT/FOREIGN DISK 

%MODNT-I-MOUNTED, mounted on DMAO: 

4 $ DISMOUNT/NOUNLOAD DISK 

5 $ INITIALIZE DISK USER_DISK 

6 $ MOUNT DISK USER_DISK 

%MODNT- I -MOUNTED, USER_DISK mounted on DMAO: 

7 $ CREATE /DIRECTORY DISK: [HELP] 
$ DIRECTORY DISK: [HELP] 
%DIRECT-W-NOFILES, no files found 

8 $ COPY SYS$HELP:NOTES.HLB DISK: [HELP] 
$ DIRECTORY DISK: [HELP] 

Directory DMAO: [HELP] 

NOTES.HLB;2 

Total of 1 file 

9 S SHOW DEVICE /FULL DISK 

Disk DMAO:, device type RK07, is online, allocated, deallocate on 
dismount, mounted, error logging enabled. 

Error count 
Owner process 
Owner process ID 
Reference count 

Volume label 

Cluster size 

Free blocks 

Extend quantity 

Mount status 

File ID cache si 

Quota cache size 

Write-thru caching enabled 

Volume is subject to mount verification, file high-water marking. 

10 $ DISMOUNT DISK 

11 $ DEALLOCATE DISK 
$ 
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Operations completed 






1940 


"SMITH" 


Owner UIC 




[VMS, 


. SMITH] 


OOOOO0A2 


Dev Prot S :RWED, 0:RWED, G: 


:RWED, 


. W : RWED 


2 


Default buffer size 






512 


"USER DISK" 


Relative volume no. 









3 


Transaction count 






1 


53691 


Maximum files allowed 






6723 


5 


Mount count 






1 


Process 


Cache name 


"_DRA0:XQPCACHE" 


ze 64 


Extent cache size 






64 
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Notes on Example 8-1: 

The following comments are keyed to the example. 

1 $ SHOW DEVICE DM: 

The SHOW DEVICE command displays the status of devices on your system. In 
this example, you request a report on the status of all available RK06 and RK07 
disk units by specifying the generic name DM as the single command parameter. 

2 $ ALLOCATE DM: DISK 

The ALLOCATE command causes the system to search for a free device of 
type DM and allocate it to your process. The message displayed at your terminal 
informs you that such a device was found: DMAO:. The system will assign the 
device name DMAO: to the logical name DISK and record it in your process 
logical name table. 

At this point, place a disk in the device and load it 

3 $ MOUNT/FOREIGN DISK 

The MOUNT/FOREIGN command makes the contents of your volume available 
to the system, but makes no assumptions concerning its file structure. DISK is the 
logical name assigned to the device name DMAO: by the ALLOCATE command 
of the preceding line. 

In this case, the disk pack is a new one. Had it been used, you would have 
required VOLPRO privilege to mount it, unless its owner UIC matched your own. 

4 $ DISMODNT/NODNLOAD DISK 

Before you can build a file structure on the volume, you must first dismount it by 
issuing the DISMOUNT command. The /NOUNLOAD qualifier tells the system 
that you want to keep the device and volume in a ready state; without it, you 
would be required to load the unit again in the machine room. DISK is the logical 
name that you equated with DMAO: when you allocated the device. 
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$ INITIALIZE DISK USER_DISK 

The INITIALIZE command builds a FILES- 11 file structure on your new volume. 
By default, you are declared its owner (that is, your UIC becomes the owner UIC 
of the disk) and all user groups are granted all types of access (READ, WRITE, 
EXECUTE, and DELETE). The volume gets the label USER_DISK and DISK is 
the logical name of the device on which it is mounted. 

$ MOUNT DISK DSER_DISK 

The MOUNT command makes the contents of the volume accessible to your 
process. The system compares the volume label to the specified label, USER_ 
DISK; a mismatch results in an error message. DISK is the logical name created 
when you allocate the RK07 disk unit (see note 2). Since the device is allocated 
to your process, no other user can access the volume. The volume protection 
code and the volume owner UIC determine your access to USER_DISK. In this 
case, you are the owner of the volume, and the volume protection code allows 
you unrestricted access to its contents. The message displayed at your terminal 
indicates that the MOUNT command executed successfully. 

$ CREATE/DIRECTORY DISK: [HELP] 
$ DIRECTORY DISK: [HELP] 

Since you own the volume, you have the right to create user file directories. The 
CREATE/DIRECTORY command creates a directory named [HELP]. By default, 
your UIC becomes the owner UIC of the directory file. The DIRECTORY 
command confirms the existence of the new directory. At the moment, the 
directory lists no files. 

$ COPY SYS$SYSHELP:NOTES.HLB DISK: [HELP] 
$ DIRECTORY DISK: [HELP] 

The COPY command transfers files from a directory on the system disk to the 
private disk you have created and mounted. In this case, you copy a file named 
NOTES.HLB in the directory logical name SYSSHELP to your private volume. 
The system fists the copied file in your newly created directory and assigns it an 
owner UIC and protection code equal to your current UIC and default protection 
code. The listing generated at your terminal by the DIRECTORY command 
confirms the success of the operation. 
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9 $ SHOW DEVICE/FULL DISK 

To determine the characteristics of a volume, mount it and issue a SHOW 
DEVICE/FULL command, specifying the device that holds the volume as the 
target device. In this example, the device is the RK07 disk unit whose logical 
name is DISK. The protection code of the device permits anyone to load and 
access a volume according to the protection code of the volume. The last block of 
information in the display generated by the SHOW DEVICE command is volume 
information. Note the following characteristics: 

Volume Label: The label of the disk is USER_DISK, the one you specified 
in the INITIALIZE command. 

Owner Die: The owner UIC associated with the disk is [VMS.SMITH], the 
default UIC of your process. 

• modnt Count: Only one process has mounted the volume (your own). 

• Relative Volume Number: The relative volume number is zero, indicating 
that this volume is not a member of a series of tapes. When a volume consists 
of more than one tape reel, it is referred to as a volume set. 

10 $ DISMOUNT DISK 

The DISMOUNT command closes access to the volume mounted on the device 
whose name is associated with DISK. The system automatically unloads the 
volume; no one can access the volume without first reloading it by depressing an 
appropriate switch on the device. At this point, remove the disk pack from the 
unit 

11 $ DEALLOCATE DISK 

The DEALLOCATE command releases the device from the control of your 
process. It does not delete the logical name DISK, however, from your process 
logical name table. 
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8.5 THE BACKUP UTILITY 

The Backup utility provides a means of protection against file or volume corruption. It 
does this by creating equivalent backup copies. BACKUP can be used to back up an 
entire volume set in a single operation, or to back up selected groups of files from a 
volume. Thus, if an original file or volume is lost, deleted, or corrupted, a backup copy 
containing the original data will be available to replace it 

When BACKUP saves files, it creates a special file in BACKUP format on the specified 
output volume. This special BACKUP file is called a save set. Only BACKUP can 
interpret save sets, because they are written in a unique BACKUP format that improves 
the efficiency of file transfer and storage. 

BACKUP is used to perform the following operations: 

• Copy files between disks. 

Save disk files to a BACKUP save set. 

• Restore files to disk from a BACKUP save set. 

The format of the Backup utility is: 

$ BACKUP/qualifier input-specifier output-specifier 

Files specified are placed in a save set. 

A save set can exist on a tape or disk. 

The Backup utility can read the format of information in a save set 

Tapes must be mounted using the /FOREIGN qualifier. 

When used with tape volumes, BACKUP can create and gain access to save sets 
only. 
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8.5.1 Save-Set Specifications 

A save-set specification is a label for a BACKUP save set. The Backup utility creates 
and labels a save set and then writes files to the save set. A save-set specification may 
include: 



A node name 

A device specification 

A directory 

A save-set name 

A period (the mandatory delimiter after the save-set name) 

A save-set type (usually BCK or SAV) 
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Example 8-2 describes how to create a save set on a tape volume. 

1 $ SET DEFAULT [SMITH] 

2 $ ALLOCATE MDAO : 

3 $ INITIALIZE MOAO: SODRCE 

4 $ MOUNT/FOREIGN MUAO : 

5 $ BACKOP/IGNORE=LABEL_PROCESSING [...] MOAO : MY_BACKOP . BCK 

6 $ DISMOUNT MUAO: 

7 $ DEALLOCATE MUAO: 

Example 8-2 Creating a Save Set on a Tape Volume 
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Notes on Example 8-2: 

1 Sets the default directory to the directory from which the files will be backed up. 

2 The ALLOCATE command allocates tape drive MUAO: for your exclusive use. 

3 Normally magnetic tapes do not have to be initialized for BACKUP operations. 
However, if a blank tape has never been initialized, or you are writing a save set 
on a tape that has a non-ANSI label, then the tape should be initialized. 

4 The MOUNT command mounts the tape on the drive. It still must be physically 
mounted on the drive, either by the user or a system operator. The /FOREIGN 
qualifier indicates that the volume is not a file-structured volume. 

5 The /IGNORE=LABEL_PROCESSING qualifier tells BACKUP not to check 
for the tape label. If no label is specified, the name of the save set must match the 
tape label. The [...] form of the DIRECTORY command indicates that all of the 
files in the default directory and any subdirectories are to be saved. They will be 
saved in the save set named MY_BACKUP.BCK. 

6 The DISMOUNT command dismounts the tape on MUAO:. 

7 The DEALLOCATE command deallocates the tape drive so other users can access 
the drive. 
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Example 8-3 shows how to transfer files to a tape volume. 

$ ALLOCATE MUAO: 

%DCL-I-ALLOC, _WHYNOT$MUA0 : allocated 

$ INITIALIZE MUAO: SOURCE 

$ MOUNT/FOREIGN MUAO: 

%MOUNT- I -MOUNTED, SOURCE mounted on _WHYNOT$MUA0 : 

$ DIRECTORY [ . . . ] 

Directory DISK: [SMITH] 

EVE.INIT;1 FORTRAN. DIR; 1 INSERT .FYI; 6 

JOE_EVE. TPU$ SECT ION ;1 LOGIN. C0M;21 PASCAL. DIR; 1 

Total of 6 files. 

Directory DISK: [SMITH. FORTRAN] 

EXAMPLES. FOR; 1 FILES.FOR;l TEXT. FOR; 1 

Total of 3 files. 

Directory DISK: [SMITH. PASCAL] 

EXAMPLE S.P AS ;1 FILES.PAS;1 TEXT.PAS;1 

Total of 3 files. 

Grand total of 3 directories, 12 files. 

$ SET DEFAULT [.FORTRAN] 

$ BACKUP/ IGNORE=LABEL_PROCES SING * . * ; * MUAO : FOR . BCK 

$ SET DEFAULT [SMITH. PASCAL] 

$ BACKUP/IGNORE=LABEL_PROCESSING *.*;* MUAO :PAS. BCK 

$ BACKUP/REWIND/LIST MUAO :PAS. BCK 
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Listing of save set(s) 



Save set : 
Written by: 
UIC: 
Date: 
Command: 

Operating system: 
CPU ID register: 
Node name : 
Written on: 
Block size: 
Group size: 
Buffer count : 



PAS.BCK 

SMITH 

[000011,000051] 

25-JAN-1988 13:30:10.59 

BACKUP/IGNORE=LABEL_PROCESSING * 

BACKUP version: V5 . 

08000000 

WHYNOT : : 

_WHYNOT$MOA0 : 

8192 

10 

3 



*;* MUA0: PAS.BCK 



[ SMITH . PASCAL] EXAMPLES . PAS ; 1 
[SMITH. PASCAL] FILES. PAS ; 1 
[SMITH. PASCAL]TEXT. PAS; 1 

Total of 3 files, 6 blocks 
End of save set 

$ BACKUP/REWIND/LIST MUA0:FOR.BCK 
Listing of save set(s) 



2 21-JAN-1988 15:17 
2 21-JAN-1988 15:18 
2 21-JAN-1988 15:17 



Save set : 
Written by: 
UIC: 
Date: 
Command : 

Operating system: 
BACKUP version: 
CPU ID register: 
Node name: 
Written on : 
Block size: 
Group size: 
Buffer count : 



FOR.BCK 

SMITH 

[000011,000051] 

25-JAN-1988 13:31:37.89 

BACKUP / 1 GNORE=LABEL_PROCESS ING 

VAX/VMS version X5 . 

V5.0 

08000000 

WHYNOT : : 

_WHYNOT$MUA0 : 

8192 

10 

3 



*,*■* MUA0:FOR.BCK 



[ SMI TH . FORTRAN ] EXAMP LE S . FOR ; 1 
[SMITH. FORTRAN] FILES .FOR; 1 
[SMITH. FORTRAN] TEXT . FOR; 1 

Total of 3 files, 6 blocks 
End of save set 

$ DISMOUNT MUA0: 
$ DEALLOCATE MUA0 : 



2 21-JAN-1988 15:16 
2 21-JAN-1988 15:16 
2 21-JAN-1988 15:16 
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Table 8-2 shows commands for displaying the characteristics of devices and volumes. 



Table 8-2 Commands for Displaying Device and Volume Characteristics 



Operation 



Format/Example 



Displaying the 
characteristics of a 
device 

Displaying the 
characteristics of a 
volume 



$ SHOW DEVICE/FULL device 

$ SHOW DEVICE/FULL DMA2 : 

$ SHOW DEVICE/FULL device 

$ SHOW DEVICE/FULL MYDISK 



Comments 



Displays the 
characteristics of 
device DMA2: 

Displays the 
characteristics of 
the volume currently 
mounted on the device 
whose logical name is 
MYDISK 
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8.6 USING PRIVATE VOLUMES 

When you want to use a volume that you have created and used previously, complete 
the following steps to make the volume available to your process: 

1. Issue a MOUNT command using a generic device specification. (If you want to 
use the same device to mount several successive volumes, you can allocate it first.) 

2. Load the volume on the device specified by the VMS system in response to your 
MOUNT request 

3. Use the volume to perform the needed functions. 

4. Issue the DISMOUNT command to break your link with the volume and free the 
device for other users. 

5. Unload the volume from the disk or tape device. 
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Example 8-4 describes how to restore files from a tape to a directory. 

1 $ MOUNT/FOREIGN MUAO : 

%MOONT- I -MOUNTED, SOURCE mounted on _WHYNOT$MUA0 : 

S DIRECTORY [SMITH. FORTRAN] 
%DIRECT-W-NOFILES, no files found 
2 

S DIRECTORY [SMITH. PASCAL] 
%DIRECT-W-NOFILES, no files found 

3 $ SET DEFAULT [SMITH. FORTRAN] 

4 $ BACKUP/IGNORE=LABEL_PROCESSING MUA0:FOR.BCK *.*;* 

5 $ DIRECTORY 

Directory DISK: [SMITH. FORTRAN] 

EXAMPLES. FOR; 1 FILES. FOR; 1 TEXT. FOR; 1 

Total of 3 files. 

6 $ SET DEFAULT [SMITH. PASCAL] 

7 $ BACKUP/REWIND/IGNORE=LABEL_PROCESSING MUAO:PAS.BCK *.*;* 

8 $ DIRECTORY 

Directory DISK: [SMITH. PASCAL] 

EXAMPLES. P AS ;1 FILES. PAS; 1 TEXT. PAS; 1 

Total of 3 files. 

Example 8-4 Restoring Files from a Tape to a Directory 
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Notes on Example 8-4: 

Example 8-4 describes the procedure to restore the two save sets named FOR.BCK 
and PAS.BCK from a magnetic tape back to two directories on your default disk. 
These save sets contain backups of the directories named [SMITH.FORTRAN] and 
[SMITH.PASCAL]. 

The following comments are keyed to the example. 

1 MODNT/FOREIGN MOAO: 

The MOUNT command creates a link between a tape device and your process. 
The system responds with a message saying the volume is loaded onto the drive. 
Some systems inform an operator that you need to have a volume loaded, and 
the operator will load the volume. On other systems, you must load the volume 
yourself. 

2 The two DIRECTORY commands show that both the subdirectories [.FORTRAN] 
and [.PASCAL] do not contain any files. 

3 The SET DEFAULT [SMITH.FORTRAN] command moves you to the 
subdirectory into which the files should be restored. 

4 BACKUP/IGNORE=LABELJPROCESSING MUA0:FOR.BCK *.*;* 
tells the system to ignore any tape label checking (via the use of the 
/IGNORE=LABEL_PROCESSING qualifier). The device and save-set name 
are given (MUA0:FOR.BCK). The wildcard asterisk syntax requests that all file 
names, file types, and version numbers in the save set (FOR.BCK) be copied to 
the subdirectory [.FORTRAN]. 

5 The DIRECTORY command is issued to confirm that all files were transferred 
from the tape device to the subdirectory [.FORTRAN]. In this example, three files 
were copied to the subdirectory. 

6 The SET DEFAULT [SMITH.PASCAL] command is given to move to the 
subdirectory [.PASCAL]. 

7 The BACKUP command is again issued, the only difference being that the save-set 
name is PAS.BCK. 

8 The DIRECTORY command is issued to confirm that all files were transferred 
from the tape device to the subdirectory [.PASCAL]. In this example, three files 
were copied to the subdirectory. 
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8.7 MAINTAINING, SHARING, AND EXTENDING PRIVATE 
VOLUMES 

In addition to the basic operations described previously, you can perform a n um ber of 
more specialized tasks on disk and tape volumes. This section examines a number of 
these, including: 

Protecting the contents of a volume 

Sharing access to a disk volume 

Mounting a volume whose label is unknown 

8.7.1 Protecting and Sharing Access to Volumes 

You control access to disk and tape volumes by the values you assign to the following 
parameters: 

• The volume owner UIC 

• The volume protection code 

The system sets these parameters when you initialize the volume, and overrides them 
when the volume is mounted. 

For you to initialize a volume, one of the following conditions must exist: 
The volume is blank 

• The owner UIC matches your own 
You have VOLPRO privilege 

Note that there are separate owner UICs and protection codes for: 

Volumes (disk and tape) 
Directories (disk only) 

• Files (disk only) 

When you want to override the protection or owner UIC set during the initializing phase, 
or extend volume access to other users, you can use qualifiers to the MOUNT command! 
Values set in the mounting phase stay in effect until the volume is dismounted. 
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8.7.2 Mounting a Volume with an Unknown Label 

From time to time, you may forget the name you assigned to a volume. To determine 
the label name, mount the volume, using the following command syntax: 

$ MOUNT/O VERRIDE=IDENTIFICATION device-name volume-label - 
logical-name 

The MOUNT/OVERRIDE command allows you to successfully mount a volume 
without knowing its label, providing that you own it or have VOLPRO privilege. 
Example 8-5 illustrates how to use the MOUNT/OVERRIDE command to mount a 
disk whose label is unknown. 
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1 $ MOUNT/OVERRIDE=IDENTIFICATION DM: UNKNOWN MYDISK 
%MOUNT- I -MOUNTED, MYVOL mounted on DMAO : 

2 $ SHOW DEVICE/FULL MYDISK 

Disk DMAO:, device type RK07, is online, allocated, deallocate on dismount, 
mounted, error logging enabled. 

Operations completed 3891 

Owner UIC [100,0] 

Dev Prot S:RWED, 0:RWED, G:RWED, W:RWED 
Default buffer size 512 



Error count 


33 


Owner process 


"SMITH" 


Owner process ID 


OO0000A2 


Reference count 


2 


Volume label 


"MYVOL" 


Cluster size 


3 


Free blocks 


53703 


Extend quantity 


5 


Mount status 


Process 


File ID cache size 


64 


Quota cache size 






Relative volume no. 
Transaction count 
Maximum files allowed 
Mount count 
Cache name 
Extent cache size 





1 

6723 

1 

"DRA0:XQPCACHE" 

64 



Write-thru caching enabled 



Volume is subject to mount verification, file high-water marking. 



Example 8-5 Mounting a Disk with an Unknown Label 
Notes on Example 8-5: 

The following comments are keyed to the example. 

1 $ MOUNT/OVERRIDE=IDENTIFICATION DM: UNKNOWN MYDISK 

The MOUNT/OVERRIDE command successfully mounts a disk for which a 
label is not specified. UNKNOWN is chosen as the volume label. You can 
specify anything for the volume label parameter or you can omit it; the MOUNT 
command ignores whatever you enter. MYDISK is the logical name of the device 
on which the volume is loaded. The message returned to your terminal reports the 
label value. 

2 $ SHOW DEVICE/FULL MYDISK 

The SHOW DEVICE/FULL command confirms that the label of the volume is 
identical to the one reported in the MOUNT message at your terminal. 
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8.8 SUMMARY 

Creating Private Volumes: The Command Sequence 

Table 8-3 lists the commands that are used to create and access disk and tape volumes. 



Table 8-3 Creating and Accessing Private Volumes 



Operation 



Allocating a Device 



Initializing a tape or disk 



Making the volume 
accessible to you 



Prohibiting further access 
to the volume 



Deallocating a device 



Comments/Format 



Allocates a device for exclusive use. 

$ ALLOCATE device [logical-name] 

Establishes volume ownership and protection. 

$ INITIALIZE device label 

You can access the device as well as manipulating files on 
the volume. 

$ MOUNT device label [logical-name] 

Closes all open files. Dismounts and unloads the volume. 

$ DISMOUNT device 

Frees the device for use by other users. 
$ DEALLOCATE device 
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The Backup Utility 

The Backup utility performs lie following operations: 

• Copies disk files 

Saves disk files to a BACKUP save set 

Restores files to disk from a BACKUP save set 
Format: 
$ BACKUP/qualifier input-specifier output-specifier 

Tapes must be mounted using the /FOREIGN qualifier to the MOUNT command. 

• Files specified are placed in a save set, which can be on tape or disk. 

When used with tape volumes, BACKUP can create and gain access to save sets 
only. 
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8.9 WRITTEN EXERCISE I 

The list below contains the major steps that you must complete to create and use a 
private volume. Indicate the order of these steps by writing the appropriate number in 
the space that precedes each one. 

1. Allocate device 

2. Deallocate device 

3. Dismount volume 

4. Initialize volume 

5. Load volume 

6. Mount volume 

7. Unload volume 
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8.10 WRITTEN EXERCISE H 

Choose the VMS command best suited to perform each of the following operations and 
write its letter in the preceding space. 

VMS Commands 

a. ALLOCATE 

b. DEALLOCATE 

c. DISMOUNT 

d. INITIALIZE 

e. MOUNT 

f. SHOW DEVICE/FULL 

Operations 

!• Build a FILES-11 structure on a disk or an ANSI Level 3 structure on 

a tape. 

2 - Terminate access by your process to the contents of a volume. 

3- Display the owner UIC and protection code of a volume. 

4 - Initiate access by your process to the contents of a volume. 

5- Release a device from exclusive use by your process. 

6- Reserve a device for exclusive use by your process. 
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8.11 WRITTEN EXERCISE EI 

Write a VMS command string to perform each of the following operations. 

1. Allocate any available RK06/RK07 device to your process and assign the logical 
name RL_DISK to it. 

2. Dismount the disk volume on RLJDISK without unloading it 

3. Allocate any available magnetic tape unit to your process and assign the logical 
name TAPE to it 

4. Initialize a tape volume you have loaded on TAPE. Assign the label TAPJBK to 
the unit. 

5. Mount TAP_BK on the tape device that you have allocated to your process so that 
the Backup utility can process it. 

6. Back up the most recent version of each file in the hierarchy associated with your 
default UFD to a save set on TAP_BK. 

7. List the contents of the save set on TAP_BK at your terminal. 

8. Terminate access to TAP_BK, allowing the system to automatically unload the 
volume. 

9. Release the tape device so others on your system can use it 

10. Delete the logical name TAPE from the logical name table that stores it 
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8.12 WRITTEN EXERCISE IV 

Write a VMS command string to perform each of the following operations. 

1. Mount a volume whose label is unknown to you on device MTA2:. 

2. Initialize a volume located on device DMA1:. Assign it the label MYVOL. Set its 
owner UIC to that of your current process. Extend all access rights to members of 
the OWNER and SYSTEM categories; deny all access rights to members of the 
GROUP and WORLD categories. 

3. Mount the volume you created in the preceding example. Set the volume UIC to 
[100,200] and allow unrestricted access to members of all user categories. 

4. Create a user file directory on MYVOL named PUBLIC, declaring the owner to 
have a UIC of [100,200]. 

5. Copy all files listed in [PUBLIC] on MYVOL to MYTAPE. 

6. Another user on your system has mounted a volume on a RL02 device. The 
volume is enabled for sharing. The volume label is SHARE_DISK. Mount the 
volume so that you can access its contents from your own process. Assign the 
logical name RL_DISK to the RL02 device. 

7. Dismount the shared disk volume on RL_DISK. If your process is the last to use 
the volume, unload it. 
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8.13 LABORATORY EXERCISE I 

Complete the following exercises at an interactive terminal. 

1. Allocate the tape. 

2. Initialize the tape, giving it a label name of MYTAPE. 

3. Mount the tape, so that BACKUP can be used. 

4. Obtain a listing of the files in your directory. 

5. Transfer all files from your directory to the tape. 

6. Confirm that all files transferred successfully to the tape. 

7. Dismount the tape. 

8. Deallocate the tape. 
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8.14 WKii I EN EXERCISE I — SOLUTIONS 

The list below contains the major steps that you must complete to create and use a 
private volume. Indicate the order of these steps by writing the appropriate number in 
the space that precedes each one. 



1. 


1 


Allocate device 


2. 


7 


Deallocate device 


3. 


5 


Dismount volume 


4. 


3 


Initialize volume 


5. 


2 


Load volume 


6. 


4 


Mount volume 


7. 


6 


Unload volume 
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8.15 WRITTEN EXERCISE H— SOLUTIONS 

Choose the VMS command best suited to perform each of the following operations and 
write its letter in the preceding space. 

VMS Commands 

a. ALLOCATE 

b. DEALLOCATE 

c. DISMOUNT 

d. INITIALIZE 

e. MOUNT 

f. SHOW DEVICE/FULL 

Operations 

1. d Build a FILES- 11 structure on a disk or an ANSI Level 3 structure on 

a tape. 

2. c Terminate access by your process to the contents of a volume. 

3. f Display the owner UIC and protection code of a volume. 

4. e Initiate access by your process to the contents of a volume. 

5. b Release a device from exclusive use by your process. 

6. a Reserve a device for exclusive use by your process. 
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8.16 WRITTEN EXERCISE HI— SOLUTIONS 

1. Allocate any available RL02 device to your process and assign the logical name 
RLJDISK to it. 

$ ALLOCATE DL: RL_DISK 

2. Dismount the disk volume on RLJDISK without unloading it 

$ DISMOUNT/NOUNLOAD RL_DISK 

3. Allocate any available magnetic tape unit to your process and assign the logical 
name TAPE to it. 

$ ALLOCATE MT : TAPE 

4. Initialize a tape volume that you have loaded on TAPE. Assign the label TAP_BK 
to the unit. 

$ INITIALIZE TAPE TAP_BK 

5. Mount TAP_BK on the tape device that you have allocated to your process so that 
the Backup utility can process it. 

$ MOUNT/FOREIGN TAPE 

6. Back up the most recent version of each file in the hierarchy associated with your 
default UFD to a save set on TAPJBK. 

$ BACKDP/IGNORE=LABELPROCESSING [...]*.* TAPE :TAP_BK.BCK 

This answer assumes that your current default directory is your UFD. 

7. List the contents of TAP_BK at your terminal. 

$ BACKUP /LI ST TAPE:TAP_BK.BCK 

8. Terminate access to TAJMBK, allowing the system to automatically unload the 
volume. 

$ DISMOUNT TAPE 

9. Release the tape device so others on your system can use it 

$ DEALLOCATE TAPE 

10. Delete the logical name TAPE from the logical name table that stores it 

$ DEASSIGN TAPE 
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8.17 WRITTEN EXERCISE IV— SOLUTIONS 

1. Mount a volume whose label is unknown to you on device MTA2: 

$ M0UNT/0VERRIDE=IDENTIFICATI0N MTA2 : 

2. Initialize a volume located on device DMA1:. Assign it the label MYVOL. Set its 
owner UIC to that of your current process. Extend all access rights to members of 
the OWNER and SYSTEM categories; deny all access rights to members of the 
GROUP and WORLD categories. 

$ INITIALIZE/NOSHARE DMA1 : MYVOL 

3. Mount the volume that you created in the preceding example. Set the volume UIC 
to [100,200] and allow unrestricted access to members of all user categories. 

$ MOUNT/OWNER_UIC=[ 100, 200] /PROTECTION (W:RWED) DMA1 : MYVOL 

4. Create a user file directory on MYVOL named PUBLIC, declaring the owner to 
have a UIC of [100,200]. 

$ CREATE/DIRECTORY/OWNER=[100,200] DMA1 : [PUBLIC] 

5. Copy all files listed in [PUBLIC] on MYVOL to MYTAPE. 

$ COPY DMA1 : [PUBLIC] * . *; * MYTAPE 

6. Another user on your system has mounted a volume on an RL02 device. The 
volume is enabled for sharing. The volume label is SHARE_DISK. Mount the 
volume so that you can access its contents from your own process. Assign the 
logical name RL_DISK to the RL02 device. 

$ MOUNT/SHARE RL: SHARE_DISK RL_DISK 

7. Dismount the shared disk volume on RL_DISK. If your process is the last to use 
the volume, unload it. 

$ DISMOUNT RL DISK 
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8. 1 8 LABORATORY EXERCISE I— SOLUTIONS 

Complete the following exercises at an interactive terminal. Note that your device 
names will differ from the device and directory names given in the solutions. 

1. Allocate the tape. 

$ ALLOCATE MOAO : 

2. Initialize the tape, giving it a label name of MYTAPE. 

S INITIALIZE MOAO: MYTAPE 

3. Mount the tape, so that BACKUP can be used. 

$ MOUNT/FOREIGN MOAO : 

4. Obtain a listing of the files in your directory. 

$ DIRECTORY 

5. Transfer all files from your directory to the tape. 

$ BACKOP/IGNORE=LABELPROCESSING *.*;* MOAO :JAN1 .BCK 

6. Confirm that all files transferred successfully to the tape. 

$ BACKUP/REWIND/LIST MOAO : JAN1 .BCK 

7. Dismount the tape. 

$ DISMOONT MOAO: 

8. Deallocate the tape. 

$ DEALLOCATE MOAO : 
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9.1 INTRODUCTION 

When you issue the PRINT command to print a file, all the system printers may already 
be in use. For this reason, the VMS system maintains a list of all print requests. This 
ordered list is called a print queue, and the requests are called print jobs. The position 
of an entry in the queue depends on its priority, size, and length of time in the queue, 
respectively. When the job moves up to the front of the queue, the VMS system passes 
it to the first available printer, which prints the file. 

The PRINT command finishes executing as soon as it enters the print job in the 
print queue. The system then displays the DCL prompt, so you can issue other DCL 
commands. You do not have to wait until the job is printed to continue your work. 
Your job is printed when it reaches the front of the queue. 

When you execute a command procedure interactively, the VMS system carries out each 
DCL command exactly as if you had typed it at your terminal. Because it executes these 
commands in the context of your interactive process, you cannot issue any additional 
DCL commands until the entire command procedure has completed. 

The VMS system creates a separate process to execute your command procedure, called 
a batch process. Because a batch process is independent of your interactive process, it 
does not prevent you from issuing DCL commands interactively. Each batch process 
is, in effect, another user of your system. To specify the command procedure you 
want executed in a batch process, you use the SUBMIT command. The VMS system 
maintains a batch queue to handle batch jobs. The SUBMIT command places your 
request, called a batch job, in the queue. When the batch job moves up to the front of 
the queue, a batch process is created to execute the job. 

Although batch jobs and print jobs have different functions, batch queues and print 
queues have much in common. The system manager customizes these queues for each 
VMS system. A queue structure that matches the resources and desired uses of the 
system can improve system performance. 
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9.2 OBJECTIVES 

To effectively use facilities for handling batch and print jobs, you should be able to 
perform the following operations by entering commands at a terminal: 

Print one or more files. 

Submit command procedures to be executed as a batch job. 

Display and modify the status or characteristics of a print or batch job. 

Delay processing of batch or print jobs. 

Delete a batch or print job from its queue. 



9.3 RESOURCES 



VMS DCL Dictionary 
Guide to Using VMS 
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9.4 PRINTING A FILE 

When you issue the PRINT command, the VMS system assigns a number to your print 
job. Your terminal displays this number, as Example 9-1 shows. Job numbers record 
the order in which jobs are queued. The PRINT command uses a default file type of 
LIS if you do not specify another type. 

By default, the system places your job in the standard system print queue, SYS$PPJNT. 
Jobs on SYS$PRINT are printed on the first available print device. In Example 9-1, the 
first available print device was LPAO:. 

$ PRINT MYFILE.TXT 

Job MYFILE (queue SYS$PRINT, entry 456) started on LPAO 

$ 

Example 9-1 Issuing the PRINT Command 
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9.4.1 Using a Particular Printer 

You can use the /QUEUE qualifier of the PRINT command to request that your job 
be printed on a particular printer. Each printer in your system has an execution queue 
associated with it. If you use the /QUEUE qualifier to specify an execution queue, only 
the device associated with that execution queue can print your job. 

The name of each execution queue is the same as the name of the associated device, 
without the colon. For example, the VMS system associates device LPAO: with 
execution queue LPAO. 

The standard system print queue, SYS$PR1NT, is called a generic queue. As a device 
becomes available, the VMS system takes a job from the front of this generic queue and 
places it on the execution queue of the available device. The device then prints the job. 

The system manager determines which execution queues receive print jobs from the 
generic print queue, and which do not. Execution queues that receive print jobs from 
the generic print queue are said to have generic printing enabled. Execution queues on 
which generic printing is not enabled cannot receive jobs from SYS$PRINT 

Usually, the system manager enables generic printing on a group of similar printers in 
a common location. A printer in a different location, or one loaded with a different 
ribbon or type of paper, would not have generic printing enabled. Figure 9-1 represents 
a system with three printers, LPAO:, LPBO:, and LPCO:. In the figure, the square to 
the right of each printer represents the print job being printed on that printer. All other 
squares represent print jobs waiting to be printed. 

Table 9-1 shows how to use the PRINT command and the SHOW QUEUE command 
to queue print jobs and display status information on them. Later examples demonstrate 
the format of this status information. 
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Table 9-1 Q 


ueuing a Print Job 




Operation 


Format/Example 


Comments 


Printing a 
single-file 
job 


$ PRINT file-specification 

$ PRINT MYTEXT 


The PRINT command 
uses a default file type 
of LIS. The file printed 
is MYTEXT.LIS in this 
example. 


Printing a 
multifile job 


$ PRINT file-specificationL...] 

$ PRINT MYTEXT , MEMO . TXT 


The files MYTEXT.LIS 
and MEMO.TXT are 
printed as a single print 
job. 


Printing a 
job on a 
specified 
printer 


$ PRINT/QUEUE=que-name file-spec 

$ PRINT/Q0EUE=LPAO MEMO. TXT 


Either the /QUEUE 
or /DEVICE qualifier 
can be used. They are 
equivalent. 


Printing 
a job at a 
specified 
time 


$ PRINT/AFTER=time file-spec 

S PRINT/AFTER=18:00 MYTEXT.TXT 


The job will be 
processed after the 
time specified in the 
/AFTER= qualifier. 
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JOB 

240 




JOB 
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JOB 
250 
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/ 



EXECUTION QUEUE LPAO 



B 



JOB 
225 



DEVICE 
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/ 



GENERIC QUEUE SYSSPRINT 



\ 



EXECUTION QUEUE LPBO 




JOB 
231 



DEVICE 
LPBO: 



JOB 
245 




JOB 
228 



EXECUTION QUEUE LPCO 
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DEVICE 
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JOB 
229 



TTB_X0338_88_S 



Figure 9-1 Execution and Generic Print Queues 
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Notes on Figure 9-1: 

1. A printer can print only one job at a time. The job being printed is called the 
current job. Job 225 is the current job on queue LPAO. Similarly, job 231 is the 
current job on queue LPBO, and job 229 is the current job on queue LPCO. 

2 Jobs waiting their turn to be printed are called pending jobs. Jobs 250, 249, and 
240 are pending jobs on queue SYS$PRINT. Similarly, jobs 228 and 245 are 
pending jobs on queue LPCO. 

3. SYS$PPJNT is a generic queue. 

Because there are no execution printers associated with a generic queue, a generic 
queue cannot have a current job. Only execution queues have current jobs. 

4. Execution queues LPAO and LPBO have generic printing enabled. Generic queue 
SYS$PRINT passes its jobs to LPAO and LPBO to be printed. 

Generic queues do not release a job to an execution queue until the associated 
device is ready to print it. That is why all pending jobs are on SYS$PRJNT, not 
on LPAO and LPBO. 

In this figure, if the VMS system queued a print job directly to LPAO, it would be 
a pending job on queue LPAO. However, this job would not necessarily be printed 
before the pending job on SYS$PRINT. The VMS system would base its selection 
of a current job for LPAO on the order in which it queued the jobs. 

5. Execution queue LPCO does not have generic printing enabled. Jobs 229, 228, 
and 245 have been queued directly to this queue. They have not passed through 
SYS$PRINT. 
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9.4.2 Specifying the Characteristics of Print Jobs 

When you queue a print job, you can also control the appearance of the job, by using 
the following positional qualifiers to the PRINT command. 

/JOBCOUNT 

Specifies the number of times your job is printed. A job can be printed from 1 to 
255 times. The default is one printing. 

/COPIES 

Specifies the number of copies to print. The number of copies can be 1 - 255. By 
default, the PRINT command prints a single copy of a file. 

/[NO]SPACE 

Controls whether output is to be double-spaced. The default is /[NO]SPACE, 
which results in single-spaced output. 

/PAGES=([lowlim,],upIim) 

Specifies the number of pages to print Lowlim is the first page printed and uplim 
is the last page printed. 

/AFTER=time 

Specifies the time to print. Time can be specified as absolute time, or a combination 
of absolute and delta time. The default is the current date and time. 

/NOTIFY 

Controls whether the system notifies you when the job is completed or aborted 
The default is /[NO]NOTIFY. 

Table 9-2 shows how to specify certain characteristics of print jobs. 
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Table 9-2 Setting the Characteristics of a Print Job 



Operation 



Printing multiple 
copies 



Comments and Examples 



Controlling the 
spacing between 
lines and pages 

Specifying number 
of pages to print 



/JOB_COUNT is a command qualifier that specifies how many 
times to duplicate the entire job. This example requests three 
printings of the file MEMO.TXT: 

$ PRINT/JOB_COUNT=number file-specification 

$ PRINT /J0B_C0UNT=3 MEMO.TXT 

/COPIES is a command qualifier that can be different for each 
file in a job. This example requests that two copies of the file 
MEMO.TXT be printed: 

$ PRINT/COPIES=number file-specifications 

$ PRINT/COPIES=2 MEMO.TXT 

This example requests that two copies of the file MEMO.TXT 
and three copies of the file MYFILE.TXT be printed: 

$ PRINT MEM0.TXT/C0PIES=2,MYFILE.TXT/C0PIES=3 

This example requests that the entire job print twice. 
/COPIES=3 requests that the second file (FTLE2.TXT) prints 
three times within each job count, giving a total of six copies for 
FHJE2.TXT. 

$ PRINT /J0B_C0UNT=2 FILE1 -TXT,FILE2 . TXT/COPIES=3 

/SPACE is a command qualifier signifying double-spaced output. 
The default of /NOSPACE results in single-spaced output. 

$ PRINT MEMO. TXT/ SPACE 

By default, all pages of a job are printed. If the lowlim 
parameter is omitted, the job begins printing on the first page. 

$ PRINT/PAGES=([lowlim,]uplim) file-specification 
In this example, pages 6 through 8 are printed: 

$ PRINT/PAGES=(6,8) MYFILE.TXT 

In this example, pages 6 through end of file are printed: 

$ PRINT/PAGES=(6,"") MYFILE.TXT 
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9.5 OBTAINING STATUS OF QUEUES 

There are several qualifiers you can use with the SHOW QUEUE command to obtain 
the status of print jobs at any given time. The format for using these qualifiers is: 

$ SHOW QUEUE/qualifiers [queue-name] 

where queue-name is the name of the printer. 

Some qualifiers also have keywords that can be used to obtain additional information. 
The format for using keywords is: 

$ SHOW QUEUE/quaIifiers[=keyword[,...]] [queue-name] 

To see all the entries on a particular printer, use the /ALLENTRIES qualifier with the 
SHOW QUEUE command. For example: 

$ SHOW QOEUE/ALL_ENTRIES SYS$PRINT 

shows you (he status of all the print jobs on the SYS$PRDSfT queue: 

Terminal queue SYS$PRINT, on WHYNOT : :$PRINTER, mounted form DEFAULT 
Jobname Username Entry Blocks Status 



MYFILE SMITH 45 60 Printing 

LICENSES SMITH 48 78 Pending 

TAGS SMITH 4 9 88 Pending 

OFFICERS SMITH 52 90 Pending 

(Example 9-2 gives you a detailed explanation of the information obtained here.) 
The BY_JOB_STATUS qualifier is used with the following keywords. 

EXECUTING (Displays executing jobs) 
HOLDING Pisplays jobs on hold) 
PENDING (Displays pending jobs) 

RETAINED (Displays jobs retained in the queue after execution) 
TIMED_RELEASE (Displays jobs on hold until a specified time) 
Example: 

$ SHOW QUEUE/BY_JOB_STATUS=TIMED_RELEASE SYS$PRINT 

Terminal queue SYS$PRINT, on WHYNOT :: $PRINTER, mounted form DEFAULT 
Jobname Osername Entry Blocks Status 



MYFILE SMITH 96 



1 Holding until 2-DEC-1988 15:00 
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The DEVICE qualifier is used with the following keywords. 

• PRINTER (Displays all print queues) 
SERVER pisplays all server queues) 
TERMINAL (Displays all terminal queues) 

Example: 

$ SHOW QUEUE/DEVICE=SERVER 

Server queue WHYNOT $ NARROW, stopped, on WHYNOT : : , mounted form DEFAULT 

Jobname Username Entry Blocks Status 

MYFILE SMITH 97 1 Holding until 2-DEC-1988 15:00 

Server queue WHYNOT $ WIDE, stopped, on WHYNOT::, mounted form DEFAULT 

The SHOW ENTRY command gives you the status of a print job by number. This 
is the number assigned by the print queue and displayed by the SHOW QUEUE 
command. For example: 

$ SHOW ENTRY 96 

Jobname Username Entry Blocks Status 



MYFILE SMITH 96 1 Holding until 2-DEC-1988 15:00 

On terminal queue SYS$PRINT 

shows you the status of print job number 96. 

The /FULL qualifier of the SHOW ENTRY command gives you additional information 
about your print job, such as when it was submitted and what the priority is. For 
example: 

$ SHOW ENTRY 96/FULL 

Jobname Username Entry Blocks Status 



MYFILE SMITH 96 1 Holding until 2-DEC-1988 15:00 

On terminal queue SYS$PRINT 

Submitted 2-DEC-1988 09:18 /FORM=DEFAULT /PRIORITY=100 
DISK: [SMITH] MYFILE.TXT;! 
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Example 9-2 shows a queue status list, displayed by the command 
SHOW QUEUE/DEVICE/ALLENTREES, that corresponds to Figure 9-1. 
The /ALLENTRIES qualifier is used because, by default, the SHOW QUEUE 
command displays only current jobs and pending jobs owned by the current process. 

$ SHOW QUEUE/DEVICE/ALL_ENTRIES 
Printer queue LPAO 
Jobname Username 



MYFILE.TXT JONES 
Printer queue LPBO 
Jobname Username 



USELESS. MEM JONES 
Printer queue LPCO 
Jobname Dsername 



SCHEDULE 

PAYROLL 

SPREAD 



SMITH 
JONES 
JONES 



Entry 
225 

Entry 

231 

Entry 

229 
228 
245 



Generic printer queue SYS$PRINT 
Jobname Username Entry 



FILE. LOG 
TYPE . COM 
CHECK 



SMITH 
JONES 
ANDERSON 



250 
249 
240 



Blocks 
10 

Blocks 
233 

Blocks 

109 
144 
156 ' 

Blocks 

198 
206 
220 



Status 

Printing at block 6 

Status 

Printing at block 34 

Status 



Printing at block 88 

Pending 

Pending 



Status 



Pending 
Pending 
Pending 



Example 9-2 Queue Status Display Corresponding to Figure 9-1 
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Notes on Example 9-2 

The following comments describe what is in each column of the display. 

1. Jobname - Usually, this is the file name of the first file in the job. Only 
information relating to your jobs is displayed. 

2. User-name - Name of user who queued the job. 

3. Entry - In this example, the entry numbers or job numbers correspond with the 
ones in Figure 9-1. Note that the list is kept in order by job size, not by job 
number. 

4. Blocks - Size of the job in blocks (one block is 512 bytes). 

5. Status - A job must have active status to compete in the queue for the printer. 
Holding means the job has inactive statusm the queue, while pending means the 
job is actively competing in the queue. The string "Printing at block 108" means 
the job is the printer's current job. 
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Example 9-3 shows a queue status list, displayed by the command 
SHOW QUEUE/DEVICES/FULL/ALL_ENTRIES. Note that, because of the 
/FULL qualifier, the list contains more information than the status list shown in 
Example 9-2. Additional lines describing the file to be printed follow each line 
describing a holding print job. 

$ SHOW QUEUE/DEVICES/FULL/ALL_ENTRIES 

Terminal queue COMP, on WHYNOT: :WHYNOT$TTA2 : , mounted form DEFAULT 
/BASE_PRIORITY=4 /DEFAULT= (FEED, FORM=DEFAULT) Lowercase 
/OWNER= [ GROUP 1, SYSTEM] /PROTECTION (S :E, 0:D, G:R, W:W) 

Printer queue LN01, on WHYNOT: :WHYNOT$LPA0: , mounted form DEFAULT 
/BASE_PRI0RITY=4 /DEFAULT= (FEED, FORM=DEFAULT) 
/LIBRARY=SYSDEVCTL_LN01 Lowercase /OWNER= [GROUP1, SYSTEM] 
/PROTECTION (S:E,0:D,G:R,W:W) /SEPARATE= (FLAG, RESET= (ANSI$RESET) ) 

Server queue NM$QUE01, on WHYNOT::, mounted form DEFAULT 
/BASE_PRIORITY=4 /DEFAULT= (FEED, FORM=DEFAULT) 

/OWNER= [ GROUP 1, SYSTEM] /PROCESSOR=NM$DAEMON /PROTECTION= (S -E O-D G-R W-Rl 
/RETAIN=ERROR ' " '*-^'"- K > 

Generic printer queue NM$QUEUE 

/GENERIC=(NM$QUE01,NM$QUE02) /OWNER= [ GROUP 1 , SYSTEM] 
/PROTECTION= (S: E, 0:D, G:R, W:R) /RETAIN=ERROR 

Jobname Username Entry Blocks Status 

IMalL SMITH lg 30 146 Holding until 24-NOV-1988 11:26 

Submitted 24-NOV-1988 11:16 /PRIORITY=100 

_$1$DUA0: [SYSCOMMON.NMAIL]NMAIL$1988112217065820.WRK;1 

Example 9-3 Full Format Queue Status Display 
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y.o MODIFYIjNu A rRiN i jwj3 

You can change the characteristics of your print job if it is not currently printing. 
Table 9-3 shows how to use the SET ENTRY command to modify the characteristics 
of a print job. 

Consult the documentation on the SET ENTRY command for a list of characteristics 
that you can change. This command can also move a job from one queue to another. 



9.6.1 Deleting a Print Job 

Table 9-3 also shows how to use the DELETE/ENTRY command to delete a job 
from a queue. You may need to do this if you accidentally print a file with non-ASCII 
characters, such as EXE or OBJ files. You can delete a job even if it is the current job. 
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Table 9-3 Modifying a Batch or Print Job 



Operation 



Comments and Examples 



Changing the The entry-number (or job number) parameter specifies the 

characteristics of a number of the job you want to change. In this example, the 
job number of copies for entry-number 100 is being changed to five. 

$ SET ENTRY entry-number/qualifier 

$ SET ENTRY 100/COPIES=5 



Moving a job to 
another queue 



In this example, the job MYFELE.TXT (entry number 90) is 
being moved from a printer using narrow paper to a printer 
using wide paper. 

$ SET ENTRY entry-number/REQUEUE=queue-name 

$ SET ENTRY 90/REQUEUE=WIDE 

Deleting a job on a Current jobs on a queue can be deleted as well as all other jobs, 
queue If a current job is deleted, its processing stops immediately. 

$ DELETE/ENTRY=job-number 

$ DELETE/ENTRY=120 
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9.7 SUBMITTING A BATCH JOB 

When you issue the SUBMIT command, the VMS system assigns a number to your 
batch job. Your terminal displays this number, as Example 9-4 shows. 

By default, your job enters the standard system batch queue, SYS$BATCH. Each job in 
this queue consists of a command procedure the system will execute in a batch process. 
(The Writing Command Procedures module covers command procedures.) 

$ SUBMIT ACTION.COM 

Job ACTION (queue SYSSBATCH, entry 136) pending 

$ 

Example 9-b Issuing the SUBMIT Command 

9.7.1 How a Batch Job Executes 

Although a batch process runs independently of your interactive process, it is like 
your interactive process in many respects. For example, the VMS system uses the 
information about you in the system user authorization file to create your batch process. 
The batch process has the same UIC, privileges, and quotas that you have when you log 
in. Also, the batch process executes your own L0GIN.COM file before executing the 
DCL commands in the submitted command procedure. 

As it executes the DCL commands in your batch job, the VMS system writes output to 
a file called the batch log. This file is created in your login directory. It usually has 
the same file name as the batch command file, and a file type of LOG. The log file is 
printed and then deleted automatically on completion of your batch job. 

The values of four process logical names the system defines for you are different for 
batch processes than they are for interactive processes. Table 9-4 shows the standard 
definitions. When batch jobs contain nested command procedures, the VMS system 
redefines these logical names for each command level. 
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Table 9-4 Logical Name Definitions for Interactive and Batch Processes 



Definition When 
Interactive Process 
Logical Name Begins to Execute 

SYS$INPUT Interactive terminal 

SYS$OUTPUT Interactive terminal 

SYS$COMMAND Interactive terminal 

SYS$ERROR Interactive terminal 



Definition When 
Batch Process 
Begins to Execute 



Batch command file 
Batch log file 
Batch command file 
Batch log file 
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Table 9—5 shows how to use qualifiers to tue §»JB ]>.»*.» conunan.^ ,0 lC* ^-.e system ~ ow 
to handle your batch log file. In particular, you can specify: 

The name of the batch log file 

Whether or not to print the batch log file if your job completes successfully 

Whether or not to delete the batch log file after it is printed 



Table 9-5 Controlling the Batch Log File 



Operation 



Comments and Examples 



Naming the batch By default, the log file has the same file name as the command 
log file file, and has the file type LOG. In this example, the log file is 

named OUTPUT.LOG instead of the default MYFILE.LOG. 

$ SUBMIT/LOG_FILE=nle-specincation 



Printing the batch 
log file 



Saving the batch 
log file 



$ SUBMIT/LOG_FILE=OUTPUT MYFILE 

By default, the log file is queued to SYS$PRINT when the batch 
job completes execution. In this example, the log file is queued 
to printer LPBO. 

$ SUBMIT/PRINTER=queue-name file-name 

$ SUBMIT/PRINTER=LPBO MYFILE 

By default, the log file is deleted after being printed. In this 
example, the log file is retained in the login directory. The 
qualifier /NOPRINTER implies the /KEEP qualifier. 

$ SUBMIT/KEEP file-specification 

$ SUBMIT/KEEP MYFILE 
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9.7.2 Writing a Batch Command Procedure 

You can run a command procedure in either of two ways: interactively, or as a batch 
job in a batch procedure. Certain differences between these two cases are discussed 
below. 

A batch process executes the system manager's login command procedure and 
your own LOGIN.COM file before executing the DCL commands in your batch 
command file. 

You can use the F$MODE() lexical function in your LOGIN.COM file to 
determine whether the process is interactive or not. If the process is not interactive, 
bypass commands that assume there is an interactive terminal, such as INQUIRE 
and SET TERMINAL. 

Also, because good programming practice requires you to spell out DCL commands 
in command procedures, you can bypass symbol definitions that define command 
abbreviations you use interactively. 

An error or severe error halts the execution of a batch job. You can use the ON 
command in your batch command file to modify the handling of errors. 

When the VMS system creates a batch process, its default directory is the one 
specified in the user authorization file. When you refer to files in your batch 
command files, make sure you know what your default directory is. 

By default, verification is on in batch processes. You can use the SET VERIFY 
command and the F$VERIFY lexical function in your batch command files to 
change verification. 
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9.7.3 Using a Particular Batch Queue 

Table 9-6 shows how to use the SUBMIT command to queue batch jobs, and Table 9-7 
shows how to use the SHOW QUEUE command to display status information on these 
jobs. Example 9-5 shows the full format of this status information. 

When you execute a command procedure interactively, you can include up to eight 
parameters on the DCL command line to define the symbols PI through P8. Note 
that you must use the /PARAMETERS qualifier of the SUBMIT command to pass 
parameters to a command procedure you submit as a batch job. 



Table 9-6 Submitting Batch Jobs 



Operation Comments and Examples 



Submitting a job The SUBMIT command uses a default file type of COM. The 
with no parameters file submitted is ACTION.COM in this example. 

$ SUBMIT file-specification 

S SUBMIT ACTION 

Submitting a job to By default, the system batch queue SYS$BATCH is used, 
a specified queue 

$ SUBMIT/QUEUE=queue-name file-specification 

$ SUBMIT/Q0EUE=SL0WBATCH ACTION 

Submitting a job The file MYFILE.TXT will be held until the specified time 

after a specified (19:00), after which it will be processed. 

time 

$ SUBMIT/AFTER=time file-specification 

$ SUBMIT/AFTER=19:00 MYFILE.TXT 

Submitting a Up to eight parameters can be specified using symbols (P1-P8). 

job that requires The symbols are local to the specified command procedures, 

parameters 

$ SUBMIT/PARAMETERS=(P1,[,...]) file-specification 

$ SUBMIT/PARAMETERS=(3,SUM) MATH 
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Example 9-5 shows a run of the command procedure COUNTl.COM. 

$! C00NT1.COM 

$! 

$ SHOW TIME 

$ SHOW LOGICAL/PROCESS/JOB 

$ EXIT 

$ SUBMIT C0UNT1.COM 

Job C0UNT1 (queue SYS$BATCH, entry 366) started on SYS$BATCH 

$ 

Output from the system's LOGIN procedure: 

$! C0UNT1.COM 

$! 

$ SHOW TIME 

13-JAN-1988 09:31:22 
$ SHOW LOGICAL/ PROCESS /JOB 

( LNM$ PROCE S SJIABLE ) 

"EVESINIT" = "SYS$LOGIN:EVE.INIT" 
"SYS$COMMAND" = "_WHYN0T$RTA1 : " 
"SYS$DISK" = "WHYN0T$D JAO : " 
"SYS$ERROR" = "_WHYN0T$RTA1 : " 
"SYS$INPUT" [super] = "_WHYNOT$DJA0 : " 
"SYS$INPUT" [exec] = "_WHYN0T$RTA1 : " 
"SYSSOUTPUT" [super] = "_WHYN0T$RTA1 : " 
"SYS$OUTPUT" [exec] = "_WHYN0T$RTA1 : " 
"TT" = "RTA1:" 

(LNM$JOB_803E1730) 

"SYS$LOGIN" = "WHYNOT$DJA0: [SMITH] " 
"SYS$LOGIN_DEVICE" = "WHYNOT$D JAO : " 
"SYSSREM_ID" = "SMITH" 
"SYS$REM_NODE" = "WHYSO::" 
"SYSSSCRATCH" = "WHYNOT$D JAO : [SMITH] " 



Example 9-5 Sample Batch Run of C0UNT1 .COM 
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Table 9-7 Displaying Batch Queue Status 



Operation 



Comments and Examples 



Displaying a list of batch 
jobs 



By default, the only jobs displayed other than your own 
are those currently executing. To display all jobs, add 
the qualifier /ALLJSNTRIES to the SHOW QUEUE 
command. For more job information, add the qualifier 
/FULL to either the SHOW QUEUE or SHOW ENTRY 
command. 



Displaying a list of batch 
jobs on a particular queue 



$ SHOW QUEUE/BATCH 

$ SHOW QOEUE/BATCH/ALL_ENTRIES 

$ SHOW ENTRY/ BATCH 

$ SHOW ENTRY/BATCH/FULL 

In any SHOW QUEUE command, you can specify a 
queue name instead of /BATCH. You can also use the 
qualifiers /FULL and /ALLJENTRIES. 

$ SHOW QUEUE queue-name 

$ SHOW QUEUE SYS$BATCH 

$ SHOW QUEUE/qualifier que-name 

$ SHOW QUEDE/ALL ENTRIES SYS$BATCH 
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Example 9-6 shows a queue status list, displayed by the command SHOW 
QUEUE/BATCH/FULL/ALL_ENTRIES. 

$ SHOW QUEUE/BATCH/FULL/ALL_ENTRIES 

Batch queue WHYNOT_SYSTEM, on WHYNOT : : 

/BASE_PRIORITY=3 /JOB_LIMIT=4 /OWNER= [GROUP 1, SYSTEM] 
/PROTECTION=(S:W,0:W,G,W) 

Jobname Osername Entry Status 

MYFILE SMITH 1388 Holding until 3-DEC-1988 18:00 

DRAFT SMITH 1425 Holding until 4-DEC-1988 01:00 

TEST JONES 1352 Holding until 7-DEC-1988 00:00 

Batch queue WHYNOTJ3ATCH, on WHYNOT:: 

/BASE_PRIORITY=2 / JOB_LIMIT=3 /OWNER= [GROUP 1, SYSTEM] 
/PROTECTION=(S:E r O:D,G:R,W:W) 

Example 9-6 Full Format Queue Status Display 
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9.8 HANDLING BATCH AND PRINT JOBS 

The VMS system handles some aspects of batch job and print job processing in exactly 
the same way. In these cases, the PRINT and SUBMIT commands use the same 
qualifiers. 

Table 9-8 shows how to specify certain characteristics common to both batch and print 
jobs, including: 

The name used to identify the job 

The node on which the job is processed 

Whether the system displays the job number when the job is queued 

Whether the system notifies you when the job completes 

Whether the input file is deleted after the job completes 
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Table 9-8 Specifying the Characteristics of Batch and Print Jobs 



Characteristic 



Comments and Examples 



Name of job 



By default, the VMS system uses the file name of the first 
file in the job. The job name appears on the flag and in 
the queue status list as the default file name of the batch 
log. 

$ SUBMIT/NAME=job-name 

$ SOBMIT/NAME=MYFILE.TXT 



Notification that job has 
been queued 



$ PRINT/NAME=job-name 

$ PRINT/NAME=MYFILE.TXT 

By default, a message is displayed notifying the user of 
the job entry number and the name of the queue in which 
the job was entered. 

$ PRINT/IDENTIFY job-name 

$ PRINT/IDENTIFY MYFILE.TXT 



Notification that job 
processing has completed 



Notifies the user when the job has been completed or 
aborted. By default, there is no notification. 

$ SUBMIT/NOTIFY file-name 

$ SOBMIT/NOTIFY MYFILE 
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9.9 BATCH AND PRINT QUEUES ETIQUETTE 

The following suggestions are given to insure that system batch and print queues flow 
efficiently and smoothly, with no "time lags" or "backups." 

Check the size of your print jobs before submitting (hem. 

If feasible, submit large print or batch jobs after hours. 

Set up a file size limit (in blocks) over which a job should be submitted after 
hours. 

If submitting a large job, verify that the paper supply is sufficient to handle that 
job, or have an operator check on the paper supply. 

Do not print files that are not compatible for the particular device. 

If possible, wait until the queue(s) are empty or handling a minimum of jobs 
before submitting your job. 

Pick up your completed job promptly. Do not allow your finished jobs to sit in the 
printer area endlessly. 
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9.10 SUMMARY 
Printing a File 

The PRINT command uses a default file type of LIS. 

• Job numbers indicate the order in the queue. 

• The print queue, named SYS$PRINT, handles print requests by default. 

• The first available printer prints the job. 

Submitting a Batch Job 

• The SUBMIT command uses a default file type COM unless another file type is 
specified. 

• Each job in the queue consists of a command procedure. 
Job numbers indicate the order in the queue. 
SYS$BATCH is the default system batch queue. 

The VMS system creates a batch process to execute the command procedure. 

Writing a Batch Command Procedure 

There are two ways to run a command procedure. 

— Interactive 

— Batch 

• By default, severe errors terminate batch job execution. 

• The batch process's default directory is the one specified as SYS$LOGIN. 

Deleting a Batch or Print Job 

• Can delete a batch or print job while it is executing or while it is pending in the 
queue. 

Use (he DELETE/ENTRY command. 
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LABORATORY EXERCISE I 

NOTE 

Several of the laboratory exercises in this module ask you to create command 

procedure files. 

Complete the following exercises at an interactive terminal. 

1. Choose a text file and print it, using the generic print queue SYS$PRINT. 

2. Use a single PRINT command to print two copies of the same file. 

3. Display a list of all queues on your system and all jobs in the queues. 

4. Select an execution queue from the queue display. (An execution queue will have 
the same name as its associated device, without the colon.) Print the same file, 
queuing it directly to the execution queue. 

5. Choose two text files. Print these two files so that you get two copies of the first 
file and three copies of the second file. 

6. Send a text file to the printer queue, requesting that the file not be printed until an 
hour from now. 

7. Display the queue status of the job waiting to be printed. Delete this job from the 
queue. 
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9.12 LABORATORY EXERCISE H 



1. Display, at your terminal, all of the batch queues on the system. 

2. Submit a command procedure to batch that displays the time, displays all processes 
on the system, and shows all logical names on the system. Save the log file. You 
will need to examine it shortly. 

3. Submit the above command procedure to batch so that the log file will not be 
printed. 

4. Submit the above command procedure to batch so that the log file will not be 
created. 

5. Examine the log file created in Step 2. Answer the following questions: 

a. Find the entry for your batch job from the SHOW SYSTEM command. What 
was its process ID? 

b. Did your LOGIN.COM file execute? Did the system-wide login procedure 
execute? 

c. How much CPU time did your batch job use to execute? 

d. How much elapsed time did your batch job use to execute? 
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9.13 LABORATORY EXERCISE I— SOLUTIONS 

1. Choose a text file and print it, using the generic print queue SYS$PRINT. 

$ PRINT FILENAME 

(FILENAME is the name of your file in all solutions.) 

2. Use a single PRINT command to print two copies of the same file. 

$ PRINT /COP IE S=2 FILENAME 

3. Display a list of all queues on your system and all jobs in the queues. 

$ SHOW QUEUE /ALL_ENTRIES 

4. Select an execution queue from the queue display. (An execution queue will have 
the same name as its associated device, without the colon.) 

$ PRINT/QUEUE=LPAO FILENAME 

(LPAO may or may not be the name of your execution queue, depending upon how 
the system is set up.) 

5. Choose two text files. Print these two files so that you get two copies of the first 
file and three copies of the second file. 

$ PRINT FIRSTFILENAME/COPIES=2,SECONDFILENAME/C0PIES=3 

6. Send a text file to the printer queue, requesting that the file not be printed until an 
hour from now. 

$ PRINT/AFTER=TIME FILENAME 

7. Display the queue status of the job waiting to be printed. Delete this job from the 
queue. 

$ SHOW QUEUE SYS$PRINT 

$ DELETE/ENTRY=n (where "n" is the entry number) 
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9.14 LABORATORY EXERCISE H— SOLUTIONS 

1. Display, at your terminal, all of the batch queues on the system. 

$ SHOW QUEUE/BATCH 

2. Submit a command procedure to batch that displays the time, displays all processes 
on the system, and shows all logical names on the system. Save the log file. You 
will need to examine it shortly. 

$! NAME OF .COM FILE 

S! 

S SHOW TIME 

S SHOW SYSTEM 

$ SHOW LOGICAL 

$ EXIT 

3. Submit the above command procedure to batch so that the log file will not be 
printed. 

$ SUBMIT/NOPRINTER FILENAME.COM 

4. Submit the above command procedure to batch so that the log file will not be 
created. 

$ SOBMIT/NOLOG FILENAME. CO 
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Examine the log file created in Step 2. Answer the following questions: 

a. Find the entry for your batch job from the SHOW SYSTEM command. What 
was its process ID? 

Your batch name entry should have a name similar to BATCHXXX (XXX 
would be the ID number of your job). Also in the right margin of the SHOW 
SYSTEM display, you should see the letter B. 

b. Did your LOGIN.COM file execute? Did the system-wide login procedure 
execute? 

The entries marked with a B are batch jobs. Both your WGIN.COM file and 
the system-wide login procedure should have executed, assuming they exist. 
You may see some of your L0GIN.COM file commands in the log file. 

c. How much CPU time did your batch job use to execute? 

d. How much elapsed time did your batch job use to execute? 

Both the CPU time and elapsed time are in the accounting information in the 
last lines of the log file. 
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1 0. 1 INTRODUCTION 

This module presents a general discussion of the steps in developing a program on a 
VAX system as well as an introduction to a sample program. 

It does not provide details regarding any of the programming languages, such as 
FORTRAN or PASCAL. 

A number of tools that significantly decrease the time spent developing VMS programs 
include: 

Interactive Text Editor (EDT) 

Compilers 

VAX MACRO Assembler 

VMS Linker 

VMS Librarian 

VMS Symbolic Debugger 

System supplied routines 

The editors, assembler, compilers, and linker are utilities that prepare source programs 
for execution. The VMS Symbolic Debugger detects logic errors in executable image 
files. 

The librarian enables you to store frequently used segments of code, such as procedures 
or functions, in specially indexed files called libraries. You can reference procedures or 
functions stored in a library with a program. The linker combines the code from the 
library with your source code to produce an executable image file. 

For the MACRO language, you store macros (definitions) in a different type of library. 
The assembler accesses libraries containing these macros to add them to a program. 

System libraries contain a large number of predefined routines that user programs (such 
as routines that manipulate strings or generate random numbers) can call. 

Refer to the Introduction to VMS System Routines manual for more information regarding 
system-supplied routines. 
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10.2 OBJECTIVES 

To use most of the programming languages, you should be familiar with the following 
program development steps: 

Creating a text file containing the source statements of the program 
Compiling or assembling the text file to create a file containing object code 
Linking the object file or files to produce a file containing executable code 
R unnin g the executable image produced from the linker 
Debugging the program to correct errors 



10.3 RESOURCES 

For more detailed explanations of developing programs, refer to the following 
documents: 

VMS DCL Dictionary 
• Guide to VMS Programming Resources 
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10.4 PROGRAM DEVELOPMENT ON A VMS SYStj&M 

To develop a program written in a VMS language, you must complete the following 

steps: 

Create a text file that contains the source statements of your program. 
Compile or assemble the text file to produce a file containing object code. 
Link the object file or files to produce an executable image file. 
Run the executable code produced by the linker. 
Debug the program to correct errors. 
Figure 10-1 illustrates the orderly flow of these five program development steps. 
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Figure 10-1 A Flow Diagram of the Five Major Programming Steps 
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Figure 10-2 The Four Program Development Commands 
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Each of the five program development steps is discussed in detail below. As you read 
each step, refer to Figures 10-1 and 10-2, which is keyed to the steps being discussed. 

1. Create a text file that contains the source statements of your program. 

Name the source file using the file type that relates to the source code programming 
language. Below are the default file types for the languages covered in this module. 



Language 


File Type 


BASIC 


BAS 


C 


C 


COBOL 


COB 


FORTRAN 


FOR 


MACRO 


MAR 


PASCAL 


PAS 


PL/I 


PLI 
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2. Compile or assemble the text file you created with an editor to produce a file 
containing object code. 

The compiler or assembler translates the source statements of each input file into 
object code, producing one or more object files of type OBJ. 

To compile or assemble the code, you must use the DCL command related to 
the language of the source code in the text file. The following are examples of 
compile and assemble commands. 



Language 

BASIC 

C 

COBOL 

FORTRAN 

MACRO 

PASCAL 

PL/I 



Compiler/ Assembler Command 



$ BASIC file-specification 
$ CC file-specification 
$ COBOL file-specification 
$ FORTRAN file-specification 
$ MACRO file-specification 
$ PASCAL file-specification 
$ PLI file-specification 
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You can list more than one input file as a parameter. The way you list these 
parameters determines how many object files the compiler or assembler creates. To 
specify your request, use either the comma (,) or the plus sign (+) as a parameter 
separator. The results of your choice follow: 

If you separate input file specifications by plus signs, the compiler creates 
one object file containing the code from all input files. 

If you separate them by commas, it creates a separate object file for each 
input file. 

If the compiler finds syntax errors in the source code, the system displays an 
appropriate message at your terminal. You can translate the message by referencing 
the appropriate language documentation. 

Use an editor to correct the source code, and submit the new version of the text 
file to the compiler or assembler for translation. 

The DCL Help facility gives you information about qualifiers when you enter the 
following command: 

HELP language name 

3. Link the object file or files to produce an executable image. 

The linker searches personal and system libraries for external procedures and 
functions that it cannot find in the specified input files. 

To link the object file(s), invoke the VMS Linker with the DCL command LINK. 
You can specify the names of the files to be linked, such as object code files or 
modules from libraries, after the command. Separate names with commas. The 
linker assumes that the file type of input files is OBJ. 

The linker's file output contains executable code assigned the file type of EXE. 

The VMS Linker Utility Reference Manual describes linker errors and recommended 
solutions. 
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4. Invoke the image activator to run the executable code produced by the linker. 

To execute a program, enter the DCL command RUN followed by the name of a 
single executable image file. The RUN command assumes that the file type field 
of the input file specification is EXE. 

You should not attempt to execute a program without correcting compiler and 
linker errors first. 

If you have corrected all obvious errors, errors output at run time can indicate 
logical errors. A logical error occurs because the statements in the program do 
not do the intended job. A logical error could produce error messages, or simply 
the wrong result. Check your results carefully. If the program receives input, you 
should execute it several times with various types of input to be sure it does the 
required job in all given situations. 

To correct the program, you must debug it to find out where the error occurs. 
When you find the error, you must modify the source program and submit it to the 
compiler or assembler and linker again. Then you can execute the new executable 
file to see if the error was corrected. 

5. Debug the program to correct errors. 

To find the cause of a logical error, you must examine the program carefully, 
looking at the source code one line at a time. Keep lists of variables and their 
contents on paper, as well as comments on loops and output to peripherals. Often, 
in larger programs, you can isolate the problem to a particular area of the program, 
saving the time of looking at every line. 

If you can isolate the problem, or if the program is not very large, it is not difficult 
to examine a program using paper; you can easily find errors. As you write larger 
programs involving more I/O, more variables, and more loops, debugging becomes 
more complicated, and the contribution the debugger makes increases. 
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10.5 THE VMS SYMBOLIC DEBUGGER UTILITY 

The VMS Symbolic Debugger simplifies your debugging job. Debug commands 
implement many of the same debugging techniques used on paper. 

The VMS Symbolic Debugger allows you to observe and manipulate your program 
interactively as it executes. By issuing debugger commands at the terminal, you can: 

Start, stop, and resume the execution of the program 

Trace the execution path of the program 

Monitor selected locations, variables, or events 

Examine and modify the contents of variables, or force events to occur 

Use breakpoints, tracepoints, and watchpoints in variables 

Test the effect of modifications without having to edit the source code, recompile, 
and, in some cases, relink 
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There are three ways to invoke the debugger: 

1. Include the debugger in the executable image. 

The debugger is included in the executable image if you enter the /DEBUG 
qualifier with the LINK command. When the system subsequendy executes your 
program, it automatically invokes the debugger, and displays the debug prompt 
(DBG>). 

Unless you also include the /DEBUG qualifier in the compiler or assembler 
command (/ENABLE=DEBUG with the MACRO command), the system will 
not include local symbol tables in the object file. The symbol tables contain the 
names and addresses of variables used in your program. For example, if you 
use the variable named ICOUNT in your FORTRAN program, by including the 
/DEBUG qualifier in the compiler command, you instruct the compiler to store 
this variable's name and address in the local symbol table it produces. Later, you 
can use the debugger to examine the contents of the variable ICOUNT and other 
variables stored in the local symbol table. 

Not all debug commands rely on the existence of local symbol tables. For 
example, the debug commands GO, STEP, and SET TRACE work without this 
information. But if you intend to examine the contents of variables, be sure to 
include the /DEBUG qualifier in your compiler or assembler command. 

2. Halt the program and invoke the debugger with the DCL command DEBUG. 

You can halt a program by entering CTRL/Y or CTRL/C, then invoke the debugger 
by entering the DCL command DEBUG. 

Use this method to halt a "hung" program, one that will not run to completion. 
The debugger can determine where the program is hung. 

This method also works for a program that is already executing in the debugger if 
you want to display the debug prompt to input further debugging commands. 

3. Run the program with the debugger. 

To run a program with the debugger, enter the /DEBUG qualifier with the RUN 
command. (Again, if you do not include the /DEBUG qualifier in the compiler or 
assembler command, the debugger will not be able to reference address locations 
by symbol names.) 

The VMS Symbolic Debugger utility has an extensive Help facility. To use this facility, 
invoke the symbolic debugger and enter the debug command HELP. 
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10.6 A SAMPLE PROGRAM - GRADES 

The FORTRAN program GRADES creates a file containing the names of students and 
the average of their grades for a particular course. The program obtains the names and 
grades from you, computes the average of the grades, and outputs the results to the 
terminal and to a designated file, ENGLISH.DAT. Example 10-1 shows the source file 
for GRADES.FOR and Example 10-2 shows the execution of GRADES. 

PROGRAM GRADES 

CHARACTER STODENT_NAME*30, DONE*4 

REAL AVERAGE 

OPEN (UNIT=1, FILE=' English', STATUS='New' ) 

10 TYPE 20 

20 FORMAT (/' Student name? ',$) 

ACCEPT 30, STUDENT_NAME 

30 FORMAT (1A30) 

CALL COMPUTE (AVERAGE) 

TYPE 40, STUDENT_NAME, AVERAGE 

WRITE (1,40) STODENT_NAME, AVERAGE 

40 FORMAT (/' Student: ', A3 0, 'Average : ',F10.1) 

TYPE 50 

50 FORMAT (/' Are you done ? (Yes/No) ',$) 

ACCEPT GO, DONE 

60 FORMAT (1A4) 

IF (DONE.NE.'Y' .AND. DONE.NE.'y') GOTO 10 

CLOSE (UNIT=1) 
END 

SUBROUTINE COMPUTE (AVERAGE) 

INTEGER ICOUNT 
REAL TOTAL, GRADE 
ICOUNT = 
TOTAL = 

10 TYPE 20 

20 FORMAT (' Input grade (or to end input): ',$) 

ACCEPT 30, GRADE 

30 FORMAT (F10.0) 

IF (GRADE. NE.0) THEN 
ICOUNT = ICOUNT + 1 
TOTAL = TOTAL + GRADE 
GO TO 10 
END IF 

40 IF (ICOUNT. NE.0) AVERAGE = TOTAL/ICOUNT 

RETURN 
END 



Example 10-1 GRADES.FOR Source File 
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10,7 EXECUTION OF GRADES 

The following example depicts a sample run of the GRADES program, using 
FORTRAN. 



$ FORTRAN GRADES 

$ LINK GRADES 

$ RON GRADES 

Student name? JOHN SMITH 



Input grade 
Input grade 
Input grade 
Input grade 



(or 
(or 
(or 
(or 



to end input) 
to end input) 
to end input ) 
to end input ) 



Student: JOHN SMITH 

Are you done ? (Yes/No) N 

Student name? MARY HAGERTY 
Input grade (or to end input) 



Input grade 
Input grade 
Input grade 



(or 
(or 
(or 



to end input) 
to end input) 
to end input) 



Student: MARY HAGERTY 
Are you done ? (Yes/No) N 
Student name? HOSIAH HOWER 



Input grade 
Input grade 
Input grade 
Input grade 



(or 
(or 
(or 
(or 



to end input) 
to end input) 
to end input) 
to end input) 



Student: HOSIAH HOWER 

Are you done ? (Yes/No) Y 

$ 

$ 

$ TYPE ENGLISH.DAT 



45 
80 
99 




82 
69 
94 




90 
78 
81 




Average: 



74.7 



Average : 



81.7 



Average : 



83.0 



Student : 

Student : 

Student : 
$ 



JOHN SMITH 
MARY HAGERTY 
HOSIAH HOWER 



Average : 


74.7 


Average : 


81.7 


Average: 


83.0 



Example 10-2 Sample Run of GRADES 
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10.8 SUMMARY 

Program Development on a VMS System 

A user must complete the following steps to develop a program: 

Create a text file that contains the source statements of your program. 
Compile or assemble the text file to produce a file containing object code. 
Link the object file or files to produce an executable image file. 
Run the executable code produced by the linker. 
Debug the program to correct errors. 

For more detailed explanations of developing programs, refer to the following 
documents: 

Guide to VMS Programming Resources 
VMS DCL Dictionary 
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There are no Exercises for this module. 



